AD-Wiki installieren und betreiben

Überblick

AD-Wiki wird als versionierter Docker-Compose-Stack ausgeliefert. Das Produktionssystem besteht aus nginx, Next.js, NestJS, PostgreSQL, Redis, dem Migrationsdienst und einem isolierten Backup-Worker. Das Quellcode-Repository muss für die Installation nicht geklont werden.

Voraussetzungen

• Linux-Server oder VM mit aktueller 64-Bit-Distribution
• Docker Engine und das Compose-Plug-in
• Mindestens 2 CPU-Kerne, 4 GB RAM und ausreichend Backup-Speicher
• Eine DNS-Adresse, die auf den Server zeigt
• Freigegebene TCP-Ports 80 und 443

Prüfe Docker und Compose:

docker --version
docker compose version

Installation

1. Release-Dateien laden

Lege ein dauerhaftes Arbeitsverzeichnis an und lade die beiden Dateien aus dem gewünschten Release:

sudo mkdir -p /opt/ad-wiki
sudo chown "$USER":"$USER" /opt/ad-wiki
cd /opt/ad-wiki

curl --fail --location --remote-name \
  https://github.com/alid-it/AD-WIKI/releases/download/v1.0.0/docker-compose.yml

curl --fail --location --remote-name \
  https://github.com/alid-it/AD-WIKI/releases/download/v1.0.0/env.production.example

cp env.production.example .env
mkdir -p backups

2. Bei GHCR anmelden

Sind die Container-Pakete noch privat, benötigt der Server einmalig ein GitHub-Token mit ausschließlich read:packages.

docker login ghcr.io --username alid-it

Öffentliche GHCR-Pakete benötigen keine Anmeldung.

3. Konfiguration bearbeiten

nano .env

Setze Domain, Version, initiales Administratorkonto und sämtliche leeren AD_WIKI_*-Werte.

4. Stack starten

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps -a

Umgebungsvariablen

Die echte .env liegt ausschließlich auf dem Server. Sie wird nicht in ein Image kopiert und darf nicht in Git landen.

Secrets erzeugen

Jede Variable erhält einen eigenen Zufallswert. Verwende denselben Wert niemals für mehrere Schlüssel.

Allgemeine Secrets mit 48 Byte

openssl rand -base64 48

Geeignet für PostgreSQL-Passwort, JWT-Secret, Monitoring-Token, Microsoft-Platzhalter und das initiale Admin-Passwort.

Verschlüsselungsschlüssel mit exakt 32 Byte

openssl rand -base64 32

• AD_WIKI_INTEGRATION_ENCRYPTION_KEY
• AD_WIKI_SSO_ENCRYPTION_KEY
• AD_WIKI_BACKUP_ENCRYPTION_KEY

TLS und Domain

Der Stack terminiert TLS im enthaltenen nginx-Container. Zertifikat, Schlüssel und Chain können als read-only Hostpfade eingebunden werden:

TLS_DOMAIN=wiki.example.com
TLS_CERT_PATH=/etc/letsencrypt/live/wiki.example.com/fullchain.pem
TLS_KEY_PATH=/etc/letsencrypt/live/wiki.example.com/privkey.pem
TLS_CA_CHAIN_PATH=
HTTP_PORT=80
HTTPS_PORT=443

Bleiben Zertifikat und Schlüssel leer, erzeugt AD-Wiki ein persistentes selbstsigniertes Fallback-Zertifikat. Das eignet sich für interne Tests, aber nicht für einen öffentlichen Betrieb.

Status und Logs

Diese Befehle decken die häufigsten Betriebsprüfungen ab:

cd /opt/ad-wiki

# Alle Container einschließlich einmaliger Jobs
docker compose ps -a

# Laufende Logs
docker compose logs -f --tail=200 api web nginx backup-worker

# Öffentliche Readiness
curl --fail https://wiki.example.com/api/v1/health/ready

Die API schreibt strukturierte JSON-Logs nach stdout. Der Metrik-Endpunkt /api/v1/health/metrics verlangt das Monitoring-Token als Bearer-Token.

Update und Rollback

Vor jedem Update: Release Notes lesen, einen erfolgreichen Backup-Job erzeugen und den bisherigen Image-Tag notieren.

AD_WIKI_IMAGE_TAG=v1.0.1
AD_WIKI_VERSION=1.0.1

docker compose config --quiet
docker compose pull
docker compose up -d --remove-orphans
docker compose ps -a

Bei rückwärtskompatiblen Migrationen kann der vorige Image-Tag wieder eingetragen werden. Bei nicht rückwärtskompatiblen Migrationen muss zusätzlich das unmittelbar vor dem Update erstellte Backup wiederhergestellt werden.

Backup und Restore

Der Backup-Worker läuft unprivilegiert mit der standardmäßigen UID/GID 1000:1000. Der Stack bereitet die benötigten Unterordner und Rechte beim Start vor.

Lokaler Pfad

mkdir -p /opt/ad-wiki/backups

# .env
BACKUP_LOCAL_PATH=./backups
BACKUP_NETWORK_PATH=./backups
BACKUP_UID=1000
BACKUP_GID=1000

SMB und Netzwerk-Mount

AD-Wiki mountet SMB nicht selbst. Binde die Freigabe zuerst auf dem Linux-Host ein und übergib anschließend den Hostpfad:

BACKUP_NETWORK_PATH=/mnt/ad-wiki-backups

SFTP und S3-kompatible Ziele werden in der Administration eingerichtet. AD-Wiki verschlüsselt deren Zugangsdaten und verlangt vor dem ersten Backup einen erfolgreichen Verbindungstest.

MCP anbinden

AD-Wiki stellt MCP über Streamable HTTP bereit. Die öffentliche Adresse ist https://deine-domain.example/mcp. OAuth- Metadaten und Browser-Login liegen auf derselben Domain.

• Vertrauenswürdige HTTPS-Zertifikatskette verwenden
• MCP_PUBLIC_URL auf den finalen /mcp-Pfad setzen
• MCP_ALLOWED_HOSTS nur mit dem DNS-Namen befüllen
• AD-Wiki-Rechte gelten unverändert für MCP-Zugriffe

Codex CLI

codex mcp add ad-wiki --url https://wiki.example.com/mcp

Beim ersten Zugriff öffnet der Client den OAuth-Login. Danach besitzt er ausschließlich die Rechte des angemeldeten Benutzers.

SSO und Microsoft Entra

OIDC-/SSO-Provider werden nach dem ersten Start in der Administration eingerichtet. Microsoft Entra benötigt eine App-Registrierung mit der Callback-Adresse der produktiven Domain.

Fehleranalyse

docker compose ps -a
docker compose logs --tail=250 database-init api web nginx backup-worker
docker compose config --quiet
curl -v https://wiki.example.com/api/v1/health/ready

Entferne vor dem Teilen von Logs Passwörter, Tokens, Cookies und Secret-Werte.