Zum Inhalt

Setup: MkDocs Material auf Cloudflare Pages mit All-Inkl-Domain

Komplettanleitung, um eine bei All-Inkl registrierte Domain mit Cloudflare Pages + Access zu nutzen. Du behältst All-Inkl als Registrar, routest aber den Traffic über Cloudflare.

Überblick

All-Inkl (Registrar)
   → Nameserver zeigen auf Cloudflare
      → Cloudflare DNS verwaltet die Domain
         → Cloudflare Pages hostet die Doku
         → Cloudflare Access schützt den Zugriff

Gesamtdauer: ca. 45 Minuten (inkl. DNS-Propagation).

Schritt 1: Domain in Cloudflare hinzufügen

  1. Gehe zu dash.cloudflare.com → Add a site.
  2. Gib deine Domain ein, z. B. meinefirma.de.
  3. Wähle den Free-Plan.
  4. Cloudflare scannt deine bestehenden DNS-Records und importiert sie automatisch. Prüfe die Liste und bestätige.
  5. Cloudflare zeigt dir zwei Nameserver an, z. B.: anna.ns.cloudflare.com bob.ns.cloudflare.com Diese brauchst du im nächsten Schritt.

Schritt 2: Nameserver bei All-Inkl ändern

  1. Logge dich bei kas.all-inkl.com ein (KAS = Kunden-Administrations-System).
  2. Gehe zu Domain → deine Domain bearbeiten (Zahnrad-Icon).
  3. Wähle Nameserver-Einstellungen → Eigene Nameserver verwenden.
  4. Trage die beiden Cloudflare-Nameserver ein: anna.ns.cloudflare.com bob.ns.cloudflare.com (Die genauen Namen stehen in deinem Cloudflare-Dashboard.)
  5. Speichern.

Wichtig: Ab jetzt verwaltet Cloudflare alle DNS-Records für diese Domain. DNS-Einträge in der All-Inkl-Oberfläche sind nicht mehr wirksam. Falls du E-Mail über All-Inkl nutzt, musst du die MX-Records in Cloudflare anlegen (siehe unten).

Die Nameserver-Änderung kann bis zu 24 Stunden dauern, meist geht es aber in unter einer Stunde. Cloudflare schickt dir eine E-Mail, sobald die Domain aktiv ist.

Schritt 3: E-Mail-Records in Cloudflare übernehmen (falls du Mail über All-Inkl nutzt)

Wenn du E-Mail-Adressen über All-Inkl verwendest (z. B. info@meinefirma.de), müssen die entsprechenden DNS-Records in Cloudflare existieren. Cloudflare importiert sie normalerweise automatisch in Schritt 1. Prüfe trotzdem, dass folgende Records vorhanden sind:

Typ Name Inhalt Proxy
MX meinefirma.de mx1.all-inkl.com (Priorität 10) DNS only
MX meinefirma.de mx2.all-inkl.com (Priorität 20) DNS only
TXT (SPF) meinefirma.de v=spf1 include:all-inkl.com ~all —

MX-Records müssen immer DNS only sein (kein Proxy), sonst funktioniert E-Mail nicht.

Falls die Records fehlen: Cloudflare Dashboard → DNS → Records → Add record.

Schritt 4: Cloudflare Pages-Projekt anlegen

  1. Installiere Wrangler:

bash npm install -g wrangler

  1. Logge dich ein:

bash npx wrangler login

  1. Erstelle das Projekt:

bash npx wrangler pages project create interne-doku --production-branch=main

  1. Notiere die Account-ID (findest du auch unter Workers & Pages im Dashboard, rechte Seitenleiste).

Schritt 5: API-Token erstellen

  1. Cloudflare Dashboard → My Profile → API Tokens → Create Token.
  2. Wähle Custom token → Get started.
  3. Konfiguriere:
Feld Wert
Token name docs-deploy
Permissions Account → Cloudflare Pages → Edit
Account Resources Nur deinen Account auswählen
  1. Create Token → Token sofort kopieren (wird nur einmal angezeigt).

Schritt 6: GitHub-Repository einrichten

  1. Erstelle ein neues privates Repo auf GitHub.

  2. Erstelle folgende Dateien:

mkdocs.yml:

site_name: Interne Dokumentation
site_url: https://docs.meinefirma.de/
theme:
  name: material
  language: de
  features:
    - navigation.instant
    - navigation.top
    - search.suggest
    - content.code.copy
plugins:
  - search:
      lang: de
nav:
  - Start: index.md

docs/index.md:

# Willkommen

Dies ist die interne Dokumentation.

.github/workflows/deploy.yml:

name: Deploy Docs to Cloudflare Pages

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  deployments: write

concurrency:
  group: deploy-docs-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build site
        run: |
          docker run --rm \
            -u "$(id -u):$(id -g)" \
            -v "${PWD}:/docs" \
            squidfunk/mkdocs-material:9 build --strict

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy site --project-name=interne-doku

.gitignore:

site/
.wrangler/

renovate.json (optional, für automatische Updates):

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"]
}

Schritt 7: GitHub Secrets hinterlegen

Im Repository unter Settings → Secrets and variables → Actions:

gh secret set CLOUDFLARE_API_TOKEN
gh secret set CLOUDFLARE_ACCOUNT_ID

Oder über das GitHub-Dashboard manuell anlegen:

Secret Wert
CLOUDFLARE_API_TOKEN Token aus Schritt 5
CLOUDFLARE_ACCOUNT_ID Account-ID aus Schritt 4

Schritt 8: Ersten Deploy auslösen

git add .
git commit -m "Initial setup"
git push

Beobachte den Workflow: GitHub → Actions → Deploy Docs to Cloudflare Pages.

Nach ca. 1 Minute ist die Seite unter https://interne-doku.pages.dev erreichbar.

Schritt 9: Custom Domain einrichten

  1. Im Cloudflare Dashboard die Suchleiste oben nutzen und nach dem Pages-Projekt suchen (z. B. interne-doku). Es erscheint unter Workers & Pages.
  2. Im Projekt: Custom domains → Set up a custom domain → docs.meinefirma.de eingeben.
  3. Cloudflare erstellt den CNAME-Record automatisch (da die Domain bereits bei Cloudflare liegt).
  4. Klicke auf Check DNS records — sollte sofort verifiziert werden.
  5. Prüfe unter DNS → Records, dass der CNAME-Eintrag auf Proxied steht.

Die Seite ist jetzt unter https://docs.meinefirma.de erreichbar.

Schritt 10: Cloudflare Access einrichten (Zugriffsschutz)

Ohne diesen Schritt ist die Doku öffentlich.

10.1 Zero Trust aktivieren

  1. Gehe zu one.dash.cloudflare.com.
  2. Aktiviere Zero Trust Free (kostenlos bis 50 Nutzer).

10.2 Login-Methode (Identity Provider) hinzufügen

  1. Im Zero Trust Dashboard die Suchleiste nutzen und nach „Login methods" oder „Authentication" suchen — die Menüstruktur ändert sich gelegentlich, die Suche ist der zuverlässigste Weg.
  2. Add new → eine Methode wählen:

One-time PIN (am einfachsten): Keine Konfiguration nötig. Nutzer bekommt einen Code per E-Mail.

GitHub (smootheres Login): Braucht eine GitHub OAuth App:

  1. GitHub → Settings → Developer settings → OAuth Apps → New OAuth App.
  2. Ausfüllen:
  3. Application name: Cloudflare Access
  4. Homepage URL: https://meinefirma.de
  5. Authorization callback URL: https://<dein-team-name>.cloudflareaccess.com/cdn-cgi/access/callback
  6. Den Team-Namen findest du im Zero Trust Dashboard unter Settings → General oder in der URL.
  7. Client ID und Client Secret (über „Generate a new client secret") kopieren.
  8. In Cloudflare unter Login methods → GitHub eintragen.
  9. PKCE und Enable Device Flow → aus lassen.

Falls du den Fehler „Unable to find your Access organization" bekommst: Der Team-Name in der Callback-URL stimmt nicht — im Zero Trust Dashboard nochmal prüfen.

10.3 Application anlegen

  1. Access → Applications → Add an application → Self-hosted.
  2. Konfiguriere:
Feld Wert
Application name Interne Dokumentation
Application domain docs.meinefirma.de
Session Duration 1 week (nach Bedarf)
  1. Klicke auf Next.

10.4 Policy anlegen

Feld Wert
Policy name Team-Zugriff
Action Allow
Include → Emails Einzelne E-Mail-Adressen eintragen

Einzelne Adressen sind sicherer als eine Domain-Wildcard — so hat nur Zugriff, wer explizit eingetragen ist.

  1. Speichern.

10.5 Auch die pages.dev-Domain absichern

Die Standard-URL interne-doku.pages.dev ist weiterhin öffentlich erreichbar. Erstelle eine zweite Access-Application mit Domain interne-doku.pages.dev und derselben Policy.

10.6 Testen

  1. Öffne https://docs.meinefirma.de im Inkognito-Fenster.
  2. Du solltest eine Login-Seite sehen.
  3. E-Mail eingeben → Code per Mail erhalten → einloggen.

Schritt 11: Lokale Vorschau (optional)

Docker muss laufen. Im Projektverzeichnis:

docker run --rm -it -p 8000:8000 -v "${PWD}:/docs" squidfunk/mkdocs-material:9 serve --dev-addr 0.0.0.0:8000

Browser: http://127.0.0.1:8000 — Live-Reload inklusive.

Alltag: Doku aktualisieren

# Markdown bearbeiten, dann:
git add docs/
git commit -m "Doku: Abschnitt X ergänzt"
git push

Der Workflow baut und deployt automatisch innerhalb von ca. 1 Minute.

Troubleshooting

Problem Lösung
Nameserver-Änderung bei All-Inkl greift nicht Kann bis zu 24h dauern. Status prüfen: dig meinefirma.de NS
E-Mail funktioniert nicht mehr MX-Records in Cloudflare prüfen, müssen auf DNS only stehen
Authentication error beim Deploy API-Token hat nicht die Berechtigung „Cloudflare Pages — Edit"
Project not found Projektname im Workflow stimmt nicht mit Cloudflare überein
Build bricht ab --strict ist aktiv — Warnungen im Log beheben
Safari findet den Server nicht Safari komplett beenden (Cmd+Q) und neu öffnen (DNS-Cache)
Seite öffentlich erreichbar Access-Application prüfen, auch *.pages.dev absichern
Custom Domain zeigt SSL-Fehler Ein paar Minuten warten, Cloudflare stellt das Zertifikat automatisch aus