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_onmitcondition: service_healthy). - Ein Rechner mit
amd64oderarm64. - 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, etwa536870912für 512 MiB) imenvironmentvonmeilisearchsetzen. - 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=8imenvironmentvonwerkbuchsetzen. - Vier Worker-Container: drei Queues und der Scheduler.
- Meilisearch, das den Suchindex im Speicher hält und beim Indexieren bis zu zwei Drittel des RAM nimmt. Auf einer knappen Maschine
- 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.
services:
werkbuch:
environment:
PHP_FPM_PM_MAX_CHILDREN: "8"
meilisearch:
environment:
MEILI_MAX_INDEXING_MEMORY: "536870912" # Bytes, 512 MiBSchnellstart: einfügen und deployen
Eine Compose-Datei mit allem darin, ohne .env:
- Den Block unten in Dockge oder Portainer als neuen Stack einfügen oder als
compose.yamlauf dem Server speichern. - Die fünf Werte oben ändern:
APP_URL(die https-Adresse des Reverse Proxys),ADMIN_EMAIL,ADMIN_PASSWORD,DB_PASSWORDundMEILISEARCH_KEY. Lange Zufallswerte nehmen, etwa mitopenssl rand -hex 24; der Schlüssel von Meilisearch braucht mindestens 16 Zeichen. - Deployen (Dockge, Portainer) oder
docker compose up -dausführen. Aufwerkbuch: readyin den Logs vonwerkbuchwarten, dannAPP_URLöffnen und mitADMIN_EMAILundADMIN_PASSWORDanmelden.
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.
# 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
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).
| Variable | Pflicht | Bedeutung |
|---|---|---|
APP_URL | ja | Ö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_LOCALE | nein | en (Standard) oder de: die Sprache der Organisation, gesetzt, wenn sie beim ersten Start entsteht. Später unter Einstellungen → Allgemein änderbar. |
WERKBUCH_IMAGE | nein | Standard baeroe/werkbuch:latest. Eine Version festlegen, siehe Versionen. |
WERKBUCH_BIND, WERKBUCH_PORT | nein | Adresse 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_EMAIL | ja | E-Mail des ersten Admins. Compose startet ohne sie nicht, auch später nicht; genutzt wird sie nur, solange werkbuch kein Konto hat. |
ADMIN_PASSWORD | erster Start | Passwort 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_PASSWORD | ja | Passwort des Datenbank-Benutzers werkbuch. MariaDB speichert es beim ersten Start; ändert man es danach in der .env, bricht die Verbindung. |
DB_ROOT_PASSWORD | ja | Passwort des root-Benutzers von MariaDB. root kann sich nur im Container mariadb anmelden. |
MEILISEARCH_KEY | ja | Master-Key von Meilisearch, mindestens 16 Zeichen (openssl rand -hex 32). Mit einem kürzeren Schlüssel startet Meilisearch nicht, und werkbuch wartet darauf. |
APP_KEY | nein | Schlü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_SECRET | nein | Schlüssel und Geheimnis der Live-Updates (Reverb). Leer: entstehen beim ersten Start und bleiben im Daten-Volume. |
TRUSTED_PROXIES | nein | IP-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_MAILER | nein | log (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_SCHEME | nein | smtps 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_PORT | mit smtp | Mailserver und Port (Standard 587). |
MAIL_USERNAME, MAIL_PASSWORD | mit smtp | Anmeldung am Mailserver, falls er eine verlangt. |
MAIL_FROM_ADDRESS, MAIL_FROM_NAME | nein | Absender jeder Mail, Standard werkbuch@example.com und werkbuch. |
ATTACHMENTS_MAX_MB | nein | Größ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_DELAY | nein | Minuten, bis die Benachrichtigungen eines Work Items in einer Mail rausgehen, Standard 5. |
WEBHOOKS_ALLOW_PRIVATE | nein | true 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_LIMIT | nein | Anfragen je Minute an die REST-API je Token oder, ohne Token, je IP-Adresse. Standard 600. |
API_SESSION_RATE_LIMIT | nein | Anfragen je Minute an die REST-API je angemeldeter Browser-Sitzung. Standard 3000. |
MCP_RATE_LIMIT | nein | Anfragen 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
docker compose up -d
docker compose logs -f werkbuch # auf "werkbuch: ready" warten, dann Strg+Cdocker 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:
- Er stoppt, wenn
DB_PASSWORDoderMEILISEARCH_KEYnochchange-meist. - Er nimmt
APP_KEY,REVERB_APP_KEYundREVERB_APP_SECRETaus 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)). - 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. - Er migriert die Datenbank.
- Er legt den ersten Admin aus
ADMIN_EMAILundADMIN_PASSWORDan, solange werkbuch kein Konto hat. - Er schickt die Einstellungen der Suchindizes an Meilisearch und füllt den Index, wenn er leer ist oder Felder dieser Version fehlen.
- Er baut seine Caches (Konfiguration mit den Schlüsseln, Routen, Views, Events).
- Er baut das OpenAPI-Dokument und warnt, wenn
ATTACHMENTS_MAX_MBgrößer ist, als PHP annimmt. - Er schreibt
werkbuch: readyins 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:
docker compose exec werkbuch php artisan app:reset-password admin@example.comOhne 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:
docker compose exec werkbuch php artisan app:reset-two-factor admin@example.comDienste
| Dienst | Aufgabe | Netze | Healthcheck |
|---|---|---|---|
werkbuch | nginx und PHP-FPM auf Port 8080, veröffentlicht als 7740; migriert beim Start, reicht /app/ (den WebSocket) an Reverb weiter | default, backend | /up für den Host aus APP_URL |
reverb | der WebSocket-Server der Live-Updates auf Port 6001 | backend | /up auf Port 6001 |
queue | Worker für die Queues mail, default, live, notifications, bulk: Einladungen und „Passwort vergessen“, Events, Live-Updates, Benachrichtigungs-Mails, Löschen von Projekten | default, backend | der Worker-Prozess läuft |
queue-index | Worker für search und media: der Suchindex und die Vorschauen von Bildern | default, backend | der Worker-Prozess läuft |
queue-webhooks | Worker für webhooks: die Zustellungen | default, backend | der Worker-Prozess läuft |
scheduler | startet die geplante Arbeit: Benachrichtigungs-Mails, Erinnerungen, Vorlagen, die nächtlichen Automatisierungen, Aufräumen | default, backend | der Scheduler-Prozess läuft |
mariadb | die Datenbank, gestartet mit --max-allowed-packet=64M | backend | MariaDB antwortet und InnoDB ist bereit |
meilisearch | die Suche | backend | /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
| Was | Wo |
|---|---|
Anhänge und ihre Vorschauen, Bilder der Organisation, der Konten und der Projekte, dazu die Schlüssel .app-key, .reverb-app-key, .reverb-app-secret | Volume 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 Queues | Volume mariadb-data |
| Suchindex | Volume 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 |
| Logs | keine 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:
- Den Dienst
mariadbund den Eintragmariadbunterdepends_onvonwerkbuchentfernen. DB_HOST,DB_PORT,DB_DATABASEundDB_USERNAMEim Blockx-werkbuch-environmentergänzen (Standardmariadb,3306,werkbuch,werkbuch);DB_PASSWORDsteht schon dort.DB_WAIT_TIMEOUTlegt fest, wie viele Sekunden der Start auf sie wartet (Standard 60).- Dem Benutzer alle Rechte an seiner Datenbank geben.
- In der Konfiguration dieses Servers
max_allowed_packetwie im Stack auf mindestens64Msetzen. 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.
# 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: