Zum Inhalt springen

Einrichtung mit Docker Compose ​

werkbuch läuft als Docker-Compose-Stack aus neun Diensten. Sechs davon kommen aus einem Image, baeroe/werkbuch (für linux/amd64 und linux/arm64): der Web-Dienst, Reverb für die Live-Updates, drei Queue-Worker und der Scheduler. Die anderen drei sind MariaDB 11.4, Meilisearch 1.56 und Gotenberg 8, das Wiki-Seiten zu PDFs macht. Alles ist über einen Port erreichbar; HTTPS kommt von einem Reverse Proxy davor (siehe Reverse Proxy).

Voraussetzungen ​

  • Docker Engine mit Compose v2.20 oder neuer: Die Dienste starten in der Reihenfolge ihrer Healthchecks (depends_on mit condition: service_healthy).
  • Ein Rechner mit amd64 oder arm64.
  • Mindestens 2 vCPU und 2 GB RAM, empfohlen 4 GB. Der Speicher geht an:
    • Meilisearch, das den Suchindex im Speicher hält und beim Indexieren bis zu zwei Drittel des RAM nimmt. Auf einer knappen Maschine MEILI_MAX_INDEXING_MEMORY (in Bytes, etwa 536870912 für 512 MiB) im environment von meilisearch setzen.
    • MariaDB.
    • PHP-FPM im Web-Dienst, mit bis zu 20 Prozessen zu höchstens 512 MB. Eine Anfrage braucht meist 30 bis 60 MB, auf einem Host mit 2 GB aber PHP_FPM_PM_MAX_CHILDREN=8 im environment von werkbuch setzen.
    • Vier Worker-Container: drei Queues und der Scheduler.
  • 10 GB Platte, dazu der Platz der Anhänge.

Einstellungen wie diese beiden gehören in eine docker-compose.override.yml neben der docker-compose.yml; docker compose liest sie von selbst. In der Standalone-Datei stehen sie direkt bei den Diensten dort.

yaml
services:
  werkbuch:
    environment:
      PHP_FPM_PM_MAX_CHILDREN: "8"
  meilisearch:
    environment:
      MEILI_MAX_INDEXING_MEMORY: "536870912" # Bytes, 512 MiB

Schnellstart: einfügen und deployen ​

Eine Compose-Datei mit allem darin, ohne .env:

  1. Den Block unten in Dockge oder Portainer als neuen Stack einfügen oder als compose.yaml auf dem Server speichern.
  2. Die fünf Werte oben ändern: APP_URL (die https-Adresse des Reverse Proxys), ADMIN_EMAIL, ADMIN_PASSWORD, DB_PASSWORD und MEILISEARCH_KEY. Lange Zufallswerte nehmen, etwa mit openssl rand -hex 24; der Schlüssel von Meilisearch braucht mindestens 16 Zeichen.
  3. Deployen (Dockge, Portainer) oder docker compose up -d ausführen. Auf werkbuch: ready in den Logs von werkbuch warten, dann APP_URL öffnen und mit ADMIN_EMAIL und ADMIN_PASSWORD anmelden.

werkbuch startet nicht, solange einer der drei Werte noch change-me ist: Der Web-Dienst stoppt bei jedem davon (beim Admin-Passwort nur, solange es kein Konto gibt), MariaDB beim Datenbank-Passwort, Meilisearch bei seinem Schlüssel. Er lauscht auf Port 7740 auf jeder Adresse des Servers (0.0.0.0): Den Reverse Proxy auf http://<server>:7740 zeigen lassen. Läuft der Proxy auf demselben Host, die Port-Zeile als "127.0.0.1:7740:8080" schreiben, damit nur der Proxy ihn erreicht, siehe Was werkbuch glaubt.

Der erste Admin entsteht beim ersten Start. Danach liest werkbuch das Admin-Passwort oben nicht mehr: dort wieder change-me eintragen, damit das eigene Passwort nicht in der Datei bleibt. Die Zeile selbst bleibt stehen, die Dienste verweisen auf sie. DB_PASSWORD so lassen: MariaDB speichert es beim ersten Start. Als root kann sich in dieser Datei niemand bei MariaDB anmelden (der Hash des Passworts passt zu keinem Passwort); Backups nutzen den Benutzer werkbuch.

yaml
# werkbuch stack in one file, for Dockge, Portainer and `docker compose up -d` without a .env.
# Edit the five values below; everything else matches docker-compose.yml (see docs/en/setup.md).
# The named volumes survive `docker compose down`; `docker compose down -v` deletes them (database, uploads, keys).

# werkbuch refuses to start while a value is still change-me: the web service stops on the admin password, MariaDB on
# the database password and Meilisearch on the key. Choose long random values (openssl rand -hex 24).
x-werkbuch:
  APP_URL: &app-url https://pm.example.com
  ADMIN_EMAIL: &admin-email admin@example.com
  # read only while there is no account yet: after the first start change-me does nothing here, keep the line
  # (the services refer to it)
  ADMIN_PASSWORD: &admin-password change-me
  DB_PASSWORD: &db-password change-me
  MEILISEARCH_KEY: &meili-key change-me

x-werkbuch-environment: &werkbuch-environment
  APP_URL: *app-url
  # the organization takes its language from this when it is created (first start)
  APP_LOCALE: "en"
  APP_KEY: ""
  REVERB_APP_KEY: ""
  REVERB_APP_SECRET: ""
  DB_PASSWORD: *db-password
  MEILISEARCH_KEY: *meili-key
  # never empty: the base image's start script stops the web service on an empty TRUSTED_PROXY* variable
  TRUSTED_PROXIES: "127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7"
  MAIL_MAILER: "log"
  MAIL_SCHEME: ""
  MAIL_HOST: ""
  MAIL_PORT: "587"
  MAIL_USERNAME: ""
  MAIL_PASSWORD: ""
  MAIL_FROM_ADDRESS: "werkbuch@example.com"
  MAIL_FROM_NAME: "werkbuch"
  # the PDF of wiki pages (WEBU-4), the service gotenberg below
  GOTENBERG_URL: http://gotenberg:3000
  ATTACHMENTS_MAX_MB: "25"
  NOTIFICATION_MAIL_DELAY: "5"
  WEBHOOKS_ALLOW_PRIVATE: "false"
  API_RATE_LIMIT: "600"
  API_SESSION_RATE_LIMIT: "3000"
  MCP_RATE_LIMIT: "300"

x-werkbuch-service: &werkbuch-service
  image: baeroe/werkbuch:latest
  restart: unless-stopped
  security_opt:
    - no-new-privileges:true
  networks:
    - default
    - backend

services:
  werkbuch:
    <<: *werkbuch-service
    ports:
      - "7740:8080"
    environment:
      <<: *werkbuch-environment
      ADMIN_EMAIL: *admin-email
      ADMIN_PASSWORD: *admin-password
    volumes:
      - werkbuch-data:/var/www/html/storage/app
    healthcheck:
      # the request carries the host of APP_URL (the app answers only to it), without the port; an IPv6 host keeps
      # its brackets. nginx does not log this request.
      # start_period is generous: the first start migrates and imports the search before nginx runs, and the workers
      # and the scheduler wait for this check (depends_on: service_healthy) because they do not migrate themselves.
      # Meilisearch must be healthy first: an unreachable index stops the whole start.
      test: ["CMD", "sh", "-c", "h=$${APP_URL#*://}; h=$${h%%/*}; case $$h in '['*) h=$${h%%]*}];; *) h=$${h%%:*};; esac; curl -fsS -o /dev/null -H \"Host: $$h\" http://localhost:8080/up"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 300s
    depends_on:
      mariadb:
        condition: service_healthy
      meilisearch:
        condition: service_healthy
      # a PDF is optional: werkbuch starts without Gotenberg and says so (503 pdf_unavailable)
      gotenberg:
        condition: service_started

  reverb:
    <<: *werkbuch-service
    # only the internal network: nginx in the web service forwards /app/ to it
    networks:
      - backend
    command: php artisan reverb:start --host=0.0.0.0 --port=6001
    environment: *werkbuch-environment
    volumes:
      - werkbuch-data:/var/www/html/storage/app:ro
    stop_signal: SIGTERM
    # without ext-uv or ev, stream_select ends at 1024 connections anyway (docs)
    ulimits:
      nofile:
        soft: 10000
        hard: 10000
    healthcheck:
      test: ["CMD", "curl", "-fsS", "-o", "/dev/null", "http://localhost:6001/up"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 30s
    depends_on:
      werkbuch:
        condition: service_healthy

  queue:
    <<: *werkbuch-service
    command: php artisan queue:work --queue=mail,default,live,notifications,bulk --sleep=1 --tries=3 --max-time=3600 --memory=384
    environment: *werkbuch-environment
    volumes:
      - werkbuch-data:/var/www/html/storage/app
    stop_signal: SIGTERM
    stop_grace_period: 30s
    healthcheck:
      test: ["CMD", "healthcheck-queue"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    depends_on:
      werkbuch:
        condition: service_healthy

  # search and previews of pictures in a worker of their own: they starved behind the events (T4-M2).
  # Exactly one container, never scale it.
  queue-index:
    <<: *werkbuch-service
    command: php artisan queue:work --queue=search,media --sleep=1 --tries=3 --max-time=3600 --memory=384
    environment: *werkbuch-environment
    volumes:
      - werkbuch-data:/var/www/html/storage/app
    stop_signal: SIGTERM
    stop_grace_period: 30s
    healthcheck:
      test: ["CMD", "healthcheck-queue"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    depends_on:
      werkbuch:
        condition: service_healthy

  # a receiver that hangs holds its worker up to 17 s per attempt (T16-M5), so webhooks get one of their own
  queue-webhooks:
    <<: *werkbuch-service
    command: php artisan queue:work --queue=webhooks --sleep=1 --tries=3 --max-time=3600 --memory=384
    environment: *werkbuch-environment
    volumes:
      - werkbuch-data:/var/www/html/storage/app
    stop_signal: SIGTERM
    stop_grace_period: 30s
    healthcheck:
      test: ["CMD", "healthcheck-queue"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    depends_on:
      werkbuch:
        condition: service_healthy

  scheduler:
    <<: *werkbuch-service
    command: php artisan schedule:work
    environment: *werkbuch-environment
    volumes:
      - werkbuch-data:/var/www/html/storage/app
    stop_signal: SIGTERM
    healthcheck:
      test: ["CMD", "healthcheck-schedule"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    depends_on:
      werkbuch:
        condition: service_healthy

  mariadb:
    image: mariadb:11.4.13@sha256:1292844148b311e4ed4300022a996d39083f415a963e970cf47cad1b3b18e3a6
    restart: unless-stopped
    # room above the largest statements of the app (the webhook deliveries of one event go in chunks of at most 8 MiB,
    # QueueDeliveries::INSERT_MAX_BYTES), four times the 16 MiB default; the CI sets the same
    command: ["--max-allowed-packet=64M"]
    # refuse the placeholder before MariaDB stores it as the password of the database. An entrypoint in Compose drops
    # the CMD of the image: without the command above, docker-entrypoint.sh would get no arguments, skip every setup,
    # exit with 0 and restart in a loop (it puts mariadbd in front of an argument starting with a dash itself).
    entrypoint:
      - sh
      - -c
      - 'if [ "$$MARIADB_PASSWORD" = change-me ]; then echo "werkbuch: set DB_PASSWORD at the top of the compose file (still change-me)" >&2; exit 1; fi; exec docker-entrypoint.sh "$$@"'
      - docker-entrypoint.sh
    environment:
      MARIADB_DATABASE: werkbuch
      MARIADB_USER: werkbuch
      MARIADB_PASSWORD: *db-password
      # nobody knows a password that hashes to this: root cannot log in at all. MARIADB_RANDOM_ROOT_PASSWORD would print
      # the password in the log of this container, which Dockge and Portainer show. Backups use the user werkbuch.
      MARIADB_ROOT_PASSWORD_HASH: "*0000000000000000000000000000000000000000"
      MARIADB_ROOT_HOST: localhost
      MARIADB_AUTO_UPGRADE: "1"
    volumes:
      - mariadb-data:/var/lib/mysql
    networks:
      - backend
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 60s

  meilisearch:
    image: getmeili/meilisearch:v1.56.1@sha256:b7ba431bf6f9b26cc86132798f3640964147a699cf23f026b74c6c05dbb1d60d
    restart: unless-stopped
    # starts Meilisearch itself (tini, then the binary), so it needs no command
    entrypoint:
      - sh
      - -c
      - 'if [ "$$MEILI_MASTER_KEY" = change-me ]; then echo "werkbuch: set MEILISEARCH_KEY at the top of the compose file (still change-me)" >&2; exit 1; fi; exec tini -- /bin/sh -c /bin/meilisearch'
    environment:
      MEILI_MASTER_KEY: *meili-key
      MEILI_ENV: production
      MEILI_NO_ANALYTICS: "true"
      # a new Meilisearch upgrades the database of the version before at start (A467); if it cannot, upgrading.md
      MEILI_UPGRADE_DB: "true"
    volumes:
      - meili-data:/meili_data
    networks:
      - backend
    healthcheck:
      test: ["CMD", "curl", "-fsS", "-o", "/dev/null", "http://localhost:7700/health"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 20s

  # the PDF of wiki pages (WEBU-4), like openbill: only in the internal network, no port. Chromium runs no JavaScript
  # and loads nothing but Gotenberg's own working files (file:///tmp/...) and data: URLs (pictures are inlined), no
  # private and no public address. Pinned like DDEV and the CI (ComposeTest).
  gotenberg:
    image: gotenberg/gotenberg:8.37.0@sha256:f29984bd1e226bf1b93ba90af06000afa8b315853e99d27b9aaa41b93f15c769
    restart: unless-stopped
    command:
      - gotenberg
      - --chromium-disable-javascript=true
      - --chromium-deny-list=^file:(?!//\/tmp/).*
      - --chromium-deny-list=^(?!(file|data):).*
      - --chromium-deny-private-ips=true
      - --chromium-deny-public-ips=true
    networks:
      - backend
    healthcheck:
      test: ["CMD", "curl", "-fsS", "-o", "/dev/null", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 20s

networks:
  default:
  backend:
    internal: true

volumes:
  werkbuch-data:
  mariadb-data:
  meili-data:

Alles andere an dieser Datei direkt darin ändern: Der Block x-werkbuch-environment hält die Einstellungen aller werkbuch-Container, die Zeile image: die Version. Wer die Einstellungen lieber in einer eigenen .env neben der Compose-Datei hat (etwa damit die Compose-Datei bei Updates unverändert bleibt), nimmt stattdessen den Weg unten.

Dateien ​

bash
mkdir werkbuch && cd werkbuch
curl -fsSLO https://raw.githubusercontent.com/baeroe/werkbuch/main/docker-compose.yml
curl -fsSL -o .env https://raw.githubusercontent.com/baeroe/werkbuch/main/.env.docker.example

.env ​

Die .env vor dem ersten Start ausfüllen. Die Passwörter sind in der Vorlage absichtlich leer: Bis sie gesetzt sind, bricht docker compose up mit DB_PASSWORD missing ab (oder DB_ROOT_PASSWORD, MEILISEARCH_KEY, APP_URL, ADMIN_EMAIL).

VariablePflichtBedeutung
APP_URLjaÖffentliche Adresse samt https://, ohne Schrägstrich am Ende, etwa https://pm.example.com. Links, Mails, die Adresse der Live-Updates und der erlaubte Host-Header kommen daher: Anfragen für jeden anderen Host bekommen 400. Cookies sind sicher markiert, wenn sie mit https:// beginnt. Ohne Proxy, für einen ersten Blick auf dem eigenen Rechner: http://localhost:7740.
APP_LOCALEneinen (Standard) oder de: die Sprache der Organisation, gesetzt, wenn sie beim ersten Start entsteht. Später unter Einstellungen → Allgemein änderbar.
WERKBUCH_IMAGEneinStandard baeroe/werkbuch:latest. Eine Version festlegen, siehe Versionen.
WERKBUCH_BIND, WERKBUCH_PORTneinAdresse und Port des Web-Dienstes auf dem Host, Standard 0.0.0.0 und 7740 (der Container lauscht auf 8080). WERKBUCH_BIND=127.0.0.1 hält den Port lokal, für einen Proxy auf demselben Host (nicht im Container), siehe Reverse Proxy.
ADMIN_EMAILjaE-Mail des ersten Admins. Compose startet ohne sie nicht, auch später nicht; genutzt wird sie nur, solange werkbuch kein Konto hat.
ADMIN_PASSWORDerster StartPasswort des ersten Admins, mindestens 8 Zeichen, nie change-me. Gelesen nur, solange werkbuch kein Konto hat; nach der ersten Anmeldung entfernen, siehe Passwörter.
DB_PASSWORDjaPasswort des Datenbank-Benutzers werkbuch. MariaDB speichert es beim ersten Start; ändert man es danach in der .env, bricht die Verbindung.
DB_ROOT_PASSWORDjaPasswort des root-Benutzers von MariaDB. root kann sich nur im Container mariadb anmelden.
MEILISEARCH_KEYjaMaster-Key von Meilisearch, mindestens 16 Zeichen (openssl rand -hex 32). Mit einem kürzeren Schlüssel startet Meilisearch nicht, und werkbuch wartet darauf.
APP_KEYneinSchlüssel der App. Leer: entsteht beim ersten Start und bleibt im Daten-Volume. Nie nachträglich ändern, siehe Was wo liegt.
REVERB_APP_KEY, REVERB_APP_SECRETneinSchlüssel und Geheimnis der Live-Updates (Reverb). Leer: entstehen beim ersten Start und bleiben im Daten-Volume.
TRUSTED_PROXIESneinIP-Adressen oder CIDR-Netze (keine Hostnamen), deren X-Forwarded-*-Header werkbuch glaubt, durch Kommas getrennt. Leer: localhost und die privaten Netze. Auf den eigenen Proxy eingrenzen, siehe Reverse Proxy.
MAIL_MAILERneinlog (Standard) schreibt Mails ins Log und verschickt nichts: Einladungen werden als Link weitergegeben, „Passwort vergessen“ fehlt, und Benachrichtigungen bleiben in der Inbox. smtp verschickt sie.
MAIL_SCHEMEneinsmtps für TLS ab dem ersten Byte. Leer: smtps auf Port 465, sonst smtp, das auf TLS wechselt, wenn der Server es anbietet.
MAIL_HOST, MAIL_PORTmit smtpMailserver und Port (Standard 587).
MAIL_USERNAME, MAIL_PASSWORDmit smtpAnmeldung am Mailserver, falls er eine verlangt.
MAIL_FROM_ADDRESS, MAIL_FROM_NAMEneinAbsender jeder Mail, Standard werkbuch@example.com und werkbuch.
ATTACHMENTS_MAX_MBneinGrößter Upload in MB, Standard 25. PHP und nginx im Image nehmen 30 und 32 MB: Ein größerer Wert wirkt darüber nicht, der Upload endet vorher mit 413 (das Log des Web-Dienstes warnt beim Start). Für größere Uploads auch diese Grenzen anheben, siehe Betrieb.
NOTIFICATION_MAIL_DELAYneinMinuten, bis die Benachrichtigungen eines Work Items in einer Mail rausgehen, Standard 5.
WEBHOOKS_ALLOW_PRIVATEneintrue lässt Webhooks private Netze erreichen (10.x, 172.16.x, 192.168.x, localhost und ähnliche); Adressen der Metadaten-Dienste von Clouds und Link-local bleiben gesperrt. Standard false. Siehe Webhooks.
API_RATE_LIMITneinAnfragen je Minute an die REST-API je Token oder, ohne Token, je IP-Adresse. Standard 600.
API_SESSION_RATE_LIMITneinAnfragen je Minute an die REST-API je angemeldeter Browser-Sitzung. Standard 3000.
MCP_RATE_LIMITneinAnfragen je Minute an den MCP-Server je Token oder je IP-Adresse. Standard 300.

Nur diese Variablen erreichen die Container: Die Compose-Datei reicht sie weiter. Alles andere gehört ins environment eines Dienstes, am besten in einer docker-compose.override.yml (siehe Voraussetzungen). Dort nie eine Variable, die mit PHP_, NGINX_, SSL_, LOG_, APACHE_, HEALTHCHECK_PATH oder TRUSTED_PROXY beginnt, leer setzen: Das Startskript des Basis-Images stoppt dann den Web-Dienst.

Die Adresse, die der Browser für die Live-Updates nutzt, kommt aus APP_URL (Host, Port und wss:// bei https://). REVERB_PUBLIC_HOST, REVERB_PUBLIC_PORT und REVERB_PUBLIC_SCHEME setzen eine andere; nötig sind sie nur, wenn der Browser Reverb nicht unter APP_URL erreicht, was mit dem Stack und einem Proxy davor nie vorkommt. Sie stehen nicht in der .env: bei Bedarf ins environment von werkbuch eintragen.

Start ​

bash
docker compose up -d
docker compose logs -f werkbuch    # auf "werkbuch: ready" warten, dann Strg+C

docker compose up -d kehrt zurück, sobald werkbuch gesund ist, weil die Worker darauf warten; beim ersten Start kann das ein paar Minuten dauern. Mit --wait kehrt es erst zurück, wenn jeder Dienst gesund ist. Dann APP_URL öffnen und mit ADMIN_EMAIL und ADMIN_PASSWORD anmelden.

Bei jedem Start macht der Web-Dienst:

  1. Er stoppt, wenn DB_PASSWORD oder MEILISEARCH_KEY noch change-me ist.
  2. Er nimmt APP_KEY, REVERB_APP_KEY und REVERB_APP_SECRET aus der Umgebung, sonst aus dem Daten-Volume, sonst erzeugt er sie einmal und schreibt sie dorthin (werkbuch: generated APP_KEY in storage/app/.app-key (data volume)).
  3. Er wartet bis zu 60 Sekunden auf die Datenbank; ist sie nicht erreichbar, stoppt er mit werkbuch: database mariadb:3306 not reachable after 60s, und Docker startet ihn neu.
  4. Er migriert die Datenbank.
  5. Er legt den ersten Admin aus ADMIN_EMAIL und ADMIN_PASSWORD an, solange werkbuch kein Konto hat.
  6. Er schickt die Einstellungen der Suchindizes an Meilisearch und füllt den Index, wenn er leer ist oder Felder dieser Version fehlen.
  7. Er baut seine Caches (Konfiguration mit den Schlüsseln, Routen, Views, Events).
  8. Er baut das OpenAPI-Dokument und warnt, wenn ATTACHMENTS_MAX_MB größer ist, als PHP annimmt.
  9. Er schreibt werkbuch: ready ins Log und startet nginx und PHP-FPM.

Scheitert ein Schritt, stoppt der Container mit einer Meldung, so bedient eine halb migrierte Instanz nie Anfragen. Meilisearch muss gesund sein, bevor der Web-Dienst startet. Die Worker, der Scheduler und Reverb starten, sobald der Web-Dienst gesund ist, lesen die Schlüssel aus dem Daten-Volume, bauen nur ihre Caches und schreiben werkbuch: ready: php artisan …; sie migrieren nie.

werkbuch: no account yet, set ADMIN_EMAIL and ADMIN_PASSWORD and run docker compose up -d heißt: Es gibt noch kein Konto, und keins ist entstanden, weil ADMIN_PASSWORD leer ist. Das Passwort in der .env setzen und docker compose up -d erneut ausführen. Sobald es ein Konto gibt, lässt jeder Start die Konten in Ruhe und endet seine Zeile mit ADMIN_EMAIL and ADMIN_PASSWORD are only used on the first start., mit oder ohne ADMIN_PASSWORD.

Passwörter ​

ADMIN_PASSWORD braucht nur der erste Start. Nach der ersten Anmeldung die Zeile aus der .env löschen und docker compose up -d ausführen, damit das Passwort weder in der Datei noch in der Umgebung des Containers steht. In der Standalone-Datei stattdessen wieder change-me eintragen (siehe Schnellstart oben).

Das eigene Passwort ändert jede Person, und einen zweiten Faktor richtet sie ein, unter Persönliche Einstellungen → Sicherheit. Ein vergessenes Passwort setzt der Server zurück; das Kommando fragt das neue zweimal ab, ohne es anzuzeigen:

bash
docker compose exec werkbuch php artisan app:reset-password admin@example.com

Ohne Terminal liest es stattdessen die erste Zeile seiner Eingabe, etwa docker compose exec -T werkbuch php artisan app:reset-password admin@example.com < neues-passwort.txt. Das Passwort ist nie ein Argument und landet so nicht im Verlauf der Shell. Das Zurücksetzen meldet das Konto überall ab; seine API-Tokens bleiben gültig.

Wer die Authenticator-App und die Recovery-Codes verloren hat, bekommt den zweiten Faktor abgeschaltet; die Person meldet sich dann nur mit dem Passwort an und kann ihn neu einrichten:

bash
docker compose exec werkbuch php artisan app:reset-two-factor admin@example.com

Dienste ​

DienstAufgabeNetzeHealthcheck
werkbuchnginx und PHP-FPM auf Port 8080, veröffentlicht als 7740; migriert beim Start, reicht /app/ (den WebSocket) an Reverb weiterdefault, backend/up für den Host aus APP_URL
reverbder WebSocket-Server der Live-Updates auf Port 6001backend/up auf Port 6001
queueWorker für die Queues mail, default, live, notifications, bulk: Einladungen und „Passwort vergessen“, Events, Live-Updates, Benachrichtigungs-Mails, Löschen von Projektendefault, backendder Worker-Prozess läuft
queue-indexWorker für search und media: der Suchindex und die Vorschauen von Bilderndefault, backendder Worker-Prozess läuft
queue-webhooksWorker für webhooks: die Zustellungendefault, backendder Worker-Prozess läuft
schedulerstartet die geplante Arbeit: Benachrichtigungs-Mails, Erinnerungen, Vorlagen, die nächtlichen Automatisierungen, Aufräumendefault, backendder Scheduler-Prozess läuft
mariadbdie Datenbank, gestartet mit --max-allowed-packet=64MbackendMariaDB antwortet und InnoDB ist bereit
meilisearchdie Suchebackend/health

backend ist ein internes Netz: kein veröffentlichter Port und kein Weg ins Internet. MariaDB, Meilisearch und Reverb hängen nur dort. Nur der Web-Dienst veröffentlicht einen Port; die Worker und der Scheduler hängen auch in default, weil sie Mails und Webhooks verschicken.

Suche und Vorschauen haben einen eigenen Worker, queue-index, damit sie nicht hinter den Events jeder Änderung warten; Webhooks haben einen, queue-webhooks, weil ein hängender Empfänger seinen Worker je Versuch bis zu 17 Sekunden hält. Von queue-index läuft genau ein Container, nie skalieren.

Alle werkbuch-Container laufen als www-data mit no-new-privileges; der Code im Image ist für sie nur lesbar.

Was wo liegt ​

WasWo
Anhänge und ihre Vorschauen, Bilder der Organisation, der Konten und der Projekte, dazu die Schlüssel .app-key, .reverb-app-key, .reverb-app-secretVolume werkbuch-data (/var/www/html/storage/app in den Containern; Reverb hängt es nur lesend ein)
Datenbank: Projekte, Work Items, Wiki, alles andere, Sitzungen und die QueuesVolume mariadb-data
SuchindexVolume meili-data; ist er leer, baut werkbuch ihn beim nächsten Start aus der Datenbank neu
Einstellungen.env neben der docker-compose.yml oder der Block oben in der Standalone-Datei
Logskeine auf der Platte: docker compose logs

Container lassen sich jederzeit neu erzeugen, die Volumes bleiben. docker compose down -v löscht sie, und mit ihnen die Datenbank, jeden Upload und die Schlüssel.

.app-key gehört in jedes Backup und darf nie verloren gehen. APP_KEY verschlüsselt die Geheimnisse der Webhooks und die zweiten Faktoren samt Recovery-Codes: Mit einem anderen Schlüssel ist jede Person mit zweitem Faktor ausgesperrt, und jeder Webhook braucht ein neues Geheimnis. APP_KEY nie nachträglich ändern. Wer ihn in der .env setzt, setzt ihn vor dem ersten Start; bei einer Instanz, die schon .app-key hat, bleibt er leer. Ein APP_KEY in der .env gewinnt vor .app-key; weichen die beiden ab, warnt jeder Start mit werkbuch: APP_KEY of the environment differs from storage/app/.app-key. Die Reverb-Schlüssel sind weniger heikel: Neue verlangen nur ein Neuladen der offenen Tabs.

Eigene MariaDB ​

Um statt des Dienstes mariadb eine vorhandene MariaDB 11.4 zu nutzen, die docker-compose.yml anpassen:

  1. Den Dienst mariadb und den Eintrag mariadb unter depends_on von werkbuch entfernen.
  2. DB_HOST, DB_PORT, DB_DATABASE und DB_USERNAME im Block x-werkbuch-environment ergänzen (Standard mariadb, 3306, werkbuch, werkbuch); DB_PASSWORD steht schon dort. DB_WAIT_TIMEOUT legt fest, wie viele Sekunden der Start auf sie wartet (Standard 60).
  3. Dem Benutzer alle Rechte an seiner Datenbank geben.
  4. In der Konfiguration dieses Servers max_allowed_packet wie im Stack auf mindestens 64M setzen. Die größten Anweisungen von werkbuch schreiben die Zustellungen der Webhooks eines Ereignisses, in Blöcken bis 8 MiB (je Webhook ein Body bis 1 MiB); der Standard von 16 MiB lässt darüber wenig Luft.

Die Datenbank muss aus dem Netz default des Stacks erreichbar sein.

Speicher ​

Uploads liegen nur im Volume werkbuch-data. S3 oder ein anderer Objektspeicher wird in dieser Version nicht unterstützt; die Platte für die Anhänge einplanen und das Volume sichern.

Versionen ​

latest folgt jedem Release. Eine Version legt WERKBUCH_IMAGE in der .env fest, als Tag wie WERKBUCH_IMAGE=baeroe/werkbuch:0.1.0 oder, damit sich das Image unter dem Tag sicher nie ändert, mit seinem Digest: WERKBUCH_IMAGE=baeroe/werkbuch:0.1.0@sha256:… (docker buildx imagetools inspect baeroe/werkbuch:0.1.0 zeigt ihn). Dann holt docker compose pull nur, was gewählt ist. In der Standalone-Datei stattdessen die Zeile image: ändern.

docker-compose.yml ​

Die vollständige Compose-Datei, dieselbe, die curl oben aus dem Main-Branch lädt. Meist bleibt sie, wie sie ist: Alles, was man einstellt, kommt in die .env.

yaml
# werkbuch stack: the web service, Reverb, three queue workers, the scheduler, MariaDB and Meilisearch.
# Docs: docs/en/setup.md. Put a `.env` next to this file (start from .env.docker.example).
# The named volumes survive `docker compose down`; `docker compose down -v` deletes them (database, uploads, keys).

x-werkbuch-environment: &werkbuch-environment
  APP_URL: "${APP_URL:?APP_URL missing (public address, see .env.docker.example)}"
  # the organization takes its language from this when it is created (first start)
  APP_LOCALE: "${APP_LOCALE:-en}"
  APP_KEY: "${APP_KEY:-}"
  REVERB_APP_KEY: "${REVERB_APP_KEY:-}"
  REVERB_APP_SECRET: "${REVERB_APP_SECRET:-}"
  DB_PASSWORD: "${DB_PASSWORD:?DB_PASSWORD missing (see .env.docker.example)}"
  MEILISEARCH_KEY: "${MEILISEARCH_KEY:?MEILISEARCH_KEY missing (see .env.docker.example)}"
  # never empty: the base image's start script stops the web service on an empty TRUSTED_PROXY* variable
  TRUSTED_PROXIES: "${TRUSTED_PROXIES:-127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7}"
  MAIL_MAILER: "${MAIL_MAILER:-log}"
  MAIL_SCHEME: "${MAIL_SCHEME:-}"
  MAIL_HOST: "${MAIL_HOST:-}"
  MAIL_PORT: "${MAIL_PORT:-587}"
  MAIL_USERNAME: "${MAIL_USERNAME:-}"
  MAIL_PASSWORD: "${MAIL_PASSWORD:-}"
  MAIL_FROM_ADDRESS: "${MAIL_FROM_ADDRESS:-werkbuch@example.com}"
  MAIL_FROM_NAME: "${MAIL_FROM_NAME:-werkbuch}"
  # the PDF of wiki pages (WEBU-4), the service gotenberg below
  GOTENBERG_URL: http://gotenberg:3000
  ATTACHMENTS_MAX_MB: "${ATTACHMENTS_MAX_MB:-25}"
  NOTIFICATION_MAIL_DELAY: "${NOTIFICATION_MAIL_DELAY:-5}"
  WEBHOOKS_ALLOW_PRIVATE: "${WEBHOOKS_ALLOW_PRIVATE:-false}"
  API_RATE_LIMIT: "${API_RATE_LIMIT:-600}"
  API_SESSION_RATE_LIMIT: "${API_SESSION_RATE_LIMIT:-3000}"
  MCP_RATE_LIMIT: "${MCP_RATE_LIMIT:-300}"

x-werkbuch-service: &werkbuch-service
  image: ${WERKBUCH_IMAGE:-baeroe/werkbuch:latest}
  restart: unless-stopped
  security_opt:
    - no-new-privileges:true
  networks:
    - default
    - backend

services:
  werkbuch:
    <<: *werkbuch-service
    ports:
      - "${WERKBUCH_BIND:-0.0.0.0}:${WERKBUCH_PORT:-7740}:8080"
    environment:
      <<: *werkbuch-environment
      ADMIN_EMAIL: "${ADMIN_EMAIL:?ADMIN_EMAIL missing (see .env.docker.example)}"
      ADMIN_PASSWORD: "${ADMIN_PASSWORD:-}"
    volumes:
      - werkbuch-data:/var/www/html/storage/app
    healthcheck:
      # the request carries the host of APP_URL (the app answers only to it), without the port; an IPv6 host keeps
      # its brackets. nginx does not log this request.
      # start_period is generous: the first start migrates and imports the search before nginx runs, and the workers
      # and the scheduler wait for this check (depends_on: service_healthy) because they do not migrate themselves.
      # Meilisearch must be healthy first: an unreachable index stops the whole start.
      test: ["CMD", "sh", "-c", "h=$${APP_URL#*://}; h=$${h%%/*}; case $$h in '['*) h=$${h%%]*}];; *) h=$${h%%:*};; esac; curl -fsS -o /dev/null -H \"Host: $$h\" http://localhost:8080/up"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 300s
    depends_on:
      mariadb:
        condition: service_healthy
      meilisearch:
        condition: service_healthy
      # a PDF is optional: werkbuch starts without Gotenberg and says so (503 pdf_unavailable)
      gotenberg:
        condition: service_started

  reverb:
    <<: *werkbuch-service
    # only the internal network: nginx in the web service forwards /app/ to it
    networks:
      - backend
    command: php artisan reverb:start --host=0.0.0.0 --port=6001
    environment: *werkbuch-environment
    volumes:
      - werkbuch-data:/var/www/html/storage/app:ro
    stop_signal: SIGTERM
    # without ext-uv or ev, stream_select ends at 1024 connections anyway (docs)
    ulimits:
      nofile:
        soft: 10000
        hard: 10000
    healthcheck:
      test: ["CMD", "curl", "-fsS", "-o", "/dev/null", "http://localhost:6001/up"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 30s
    depends_on:
      werkbuch:
        condition: service_healthy

  queue:
    <<: *werkbuch-service
    command: php artisan queue:work --queue=mail,default,live,notifications,bulk --sleep=1 --tries=3 --max-time=3600 --memory=384
    environment: *werkbuch-environment
    volumes:
      - werkbuch-data:/var/www/html/storage/app
    stop_signal: SIGTERM
    stop_grace_period: 30s
    healthcheck:
      test: ["CMD", "healthcheck-queue"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    depends_on:
      werkbuch:
        condition: service_healthy

  # search and previews of pictures in a worker of their own: they starved behind the events (T4-M2).
  # Exactly one container, never scale it.
  queue-index:
    <<: *werkbuch-service
    command: php artisan queue:work --queue=search,media --sleep=1 --tries=3 --max-time=3600 --memory=384
    environment: *werkbuch-environment
    volumes:
      - werkbuch-data:/var/www/html/storage/app
    stop_signal: SIGTERM
    stop_grace_period: 30s
    healthcheck:
      test: ["CMD", "healthcheck-queue"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    depends_on:
      werkbuch:
        condition: service_healthy

  # a receiver that hangs holds its worker up to 17 s per attempt (T16-M5), so webhooks get one of their own
  queue-webhooks:
    <<: *werkbuch-service
    command: php artisan queue:work --queue=webhooks --sleep=1 --tries=3 --max-time=3600 --memory=384
    environment: *werkbuch-environment
    volumes:
      - werkbuch-data:/var/www/html/storage/app
    stop_signal: SIGTERM
    stop_grace_period: 30s
    healthcheck:
      test: ["CMD", "healthcheck-queue"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    depends_on:
      werkbuch:
        condition: service_healthy

  scheduler:
    <<: *werkbuch-service
    command: php artisan schedule:work
    environment: *werkbuch-environment
    volumes:
      - werkbuch-data:/var/www/html/storage/app
    stop_signal: SIGTERM
    healthcheck:
      test: ["CMD", "healthcheck-schedule"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    depends_on:
      werkbuch:
        condition: service_healthy

  mariadb:
    image: mariadb:11.4.13@sha256:1292844148b311e4ed4300022a996d39083f415a963e970cf47cad1b3b18e3a6
    restart: unless-stopped
    # room above the largest statements of the app (the webhook deliveries of one event go in chunks of at most 8 MiB,
    # QueueDeliveries::INSERT_MAX_BYTES), four times the 16 MiB default; the CI sets the same
    command: ["--max-allowed-packet=64M"]
    environment:
      MARIADB_DATABASE: werkbuch
      MARIADB_USER: werkbuch
      MARIADB_PASSWORD: "${DB_PASSWORD:?DB_PASSWORD missing (see .env.docker.example)}"
      MARIADB_ROOT_PASSWORD: "${DB_ROOT_PASSWORD:?DB_ROOT_PASSWORD missing (see .env.docker.example)}"
      MARIADB_ROOT_HOST: localhost
      MARIADB_AUTO_UPGRADE: "1"
    volumes:
      - mariadb-data:/var/lib/mysql
    networks:
      - backend
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 60s

  meilisearch:
    image: getmeili/meilisearch:v1.56.1@sha256:b7ba431bf6f9b26cc86132798f3640964147a699cf23f026b74c6c05dbb1d60d
    restart: unless-stopped
    environment:
      MEILI_MASTER_KEY: "${MEILISEARCH_KEY:?MEILISEARCH_KEY missing (see .env.docker.example)}"
      MEILI_ENV: production
      MEILI_NO_ANALYTICS: "true"
      # a new Meilisearch upgrades the database of the version before at start (A467); if it cannot, upgrading.md
      MEILI_UPGRADE_DB: "true"
    volumes:
      - meili-data:/meili_data
    networks:
      - backend
    healthcheck:
      test: ["CMD", "curl", "-fsS", "-o", "/dev/null", "http://localhost:7700/health"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 20s

  # the PDF of wiki pages (WEBU-4), like openbill: only in the internal network, no port. Chromium runs no JavaScript
  # and loads nothing but Gotenberg's own working files (file:///tmp/...) and data: URLs (pictures are inlined), no
  # private and no public address. Pinned like DDEV and the CI (ComposeTest).
  gotenberg:
    image: gotenberg/gotenberg:8.37.0@sha256:f29984bd1e226bf1b93ba90af06000afa8b315853e99d27b9aaa41b93f15c769
    restart: unless-stopped
    command:
      - gotenberg
      - --chromium-disable-javascript=true
      - --chromium-deny-list=^file:(?!//\/tmp/).*
      - --chromium-deny-list=^(?!(file|data):).*
      - --chromium-deny-private-ips=true
      - --chromium-deny-public-ips=true
    networks:
      - backend
    healthcheck:
      test: ["CMD", "curl", "-fsS", "-o", "/dev/null", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 20s

networks:
  default:
  backend:
    internal: true

volumes:
  werkbuch-data:
  mariadb-data:
  meili-data: