Setup with Docker Compose
werkbuch runs as a Docker Compose stack of nine services. Six of them come from one image, baeroe/werkbuch (for linux/amd64 and linux/arm64): the web service, Reverb for the live updates, three queue workers and the scheduler. The other three are MariaDB 11.4, Meilisearch 1.56 and Gotenberg 8, which turns wiki pages into PDFs. Everything is reachable over one port; HTTPS comes from a reverse proxy in front of it (see Reverse proxy).
Requirements
- Docker Engine with Compose v2.20 or newer: the services start in the order of their health checks (
depends_onwithcondition: service_healthy). - A machine with
amd64orarm64. - At least 2 vCPU and 2 GB of RAM, 4 GB recommended. The memory goes to:
- Meilisearch, which keeps the search index in memory and takes up to two thirds of the RAM while it indexes. On a tight machine, set
MEILI_MAX_INDEXING_MEMORY(in bytes, for example536870912for 512 MiB) in theenvironmentofmeilisearch. - MariaDB.
- PHP-FPM in the web service, with up to 20 processes of at most 512 MB each. A request usually takes 30 to 60 MB, but on a 2 GB host set
PHP_FPM_PM_MAX_CHILDREN=8in theenvironmentofwerkbuch. - Four worker containers: three queues and the scheduler.
- Meilisearch, which keeps the search index in memory and takes up to two thirds of the RAM while it indexes. On a tight machine, set
- 10 GB of disk, plus what the attachments take.
Settings like these two belong in a docker-compose.override.yml next to docker-compose.yml; docker compose reads it on its own. In the standalone file, add them to the services there.
services:
werkbuch:
environment:
PHP_FPM_PM_MAX_CHILDREN: "8"
meilisearch:
environment:
MEILI_MAX_INDEXING_MEMORY: "536870912" # bytes, 512 MiBQuick start: paste and deploy
One compose file with everything in it, no .env:
- Paste the block below into a new stack in Dockge or Portainer, or save it as
compose.yamlon your server. - Change the five values at the top:
APP_URL(the https address of your reverse proxy),ADMIN_EMAIL,ADMIN_PASSWORD,DB_PASSWORDandMEILISEARCH_KEY. Choose long random values, for example withopenssl rand -hex 24; the key of Meilisearch needs at least 16 characters. - Deploy (Dockge, Portainer) or run
docker compose up -d. Wait forwerkbuch: readyin the logs ofwerkbuch, then openAPP_URLand sign in withADMIN_EMAILandADMIN_PASSWORD.
werkbuch refuses to start while one of the three is still change-me: the web service stops on each of them (on the admin password only as long as there is no account), MariaDB on the database password, Meilisearch on its key. It listens on port 7740 on every address of the server (0.0.0.0): point your reverse proxy at http://<server>:7740. With the proxy on the same host, write the port line as "127.0.0.1:7740:8080" so that only the proxy reaches it, see What werkbuch trusts.
The first admin is created on the first start. After that the admin password at the top is no longer read: put change-me back there, so your password is not left in the file. Keep the line itself, the services refer to it. Keep DB_PASSWORD as it is: MariaDB stores it on the first start. Nobody can log in to MariaDB as root in this file (its password hash matches no password); backups use the user 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:To change anything else of this file, edit it in place: the block x-werkbuch-environment holds the settings of every werkbuch container, the line image: the version. If you prefer the settings in a separate .env next to the compose file (for example to keep the compose file unchanged on updates), use the way below instead.
Files
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
Fill in .env before the first start. The passwords are empty in the template on purpose: until they are set, docker compose up stops with DB_PASSWORD missing (or DB_ROOT_PASSWORD, MEILISEARCH_KEY, APP_URL, ADMIN_EMAIL).
| Variable | Required | Meaning |
|---|---|---|
APP_URL | yes | Public address including https://, without a trailing slash, e.g. https://pm.example.com. Links, mails, the address of the live updates and the allowed Host header come from it: requests for any other host get 400. Cookies are marked secure when it starts with https://. Without a proxy, for a first look on your own machine: http://localhost:7740. |
APP_LOCALE | no | en (default) or de: the language of the organization, set when it is created on the first start. Change it later under Settings → General. |
WERKBUCH_IMAGE | no | Default baeroe/werkbuch:latest. Pin a version, see Versions. |
WERKBUCH_BIND, WERKBUCH_PORT | no | Host address and port of the web service, default 0.0.0.0 and 7740 (the container listens on 8080). WERKBUCH_BIND=127.0.0.1 keeps the port local, for a proxy on the same host (not in a container), see Reverse proxy. |
ADMIN_EMAIL | yes | Email of the first admin. Compose refuses to start without it, also later; it is only used while werkbuch has no account. |
ADMIN_PASSWORD | first start | Password of the first admin, at least 8 characters, never change-me. Read only while werkbuch has no account; remove it once you have signed in, see Passwords. |
DB_PASSWORD | yes | Password of the database user werkbuch. MariaDB stores it on the first start; changing it in .env afterwards breaks the connection. |
DB_ROOT_PASSWORD | yes | Password of the MariaDB root user. Root can only log in from inside the mariadb container. |
MEILISEARCH_KEY | yes | Master key of Meilisearch, at least 16 characters (openssl rand -hex 32). With a shorter key Meilisearch does not start, and werkbuch waits for it. |
APP_KEY | no | Encryption key of the app. Empty: made on the first start and kept in the data volume. Never change it later, see What lives where. |
REVERB_APP_KEY, REVERB_APP_SECRET | no | Key and secret of the live updates (Reverb). Empty: made on the first start and kept in the data volume. |
TRUSTED_PROXIES | no | IP addresses or CIDR networks (no host names) whose X-Forwarded-* headers werkbuch believes, comma-separated. Empty: localhost and the private networks. Narrow it to your proxy, see Reverse proxy. |
MAIL_MAILER | no | log (default) writes mails to the log and sends nothing: invitations are handed on as links, “Forgot password” is hidden and notifications stay in the inbox. smtp sends them. |
MAIL_SCHEME | no | smtps for TLS from the first byte. Empty: smtps on port 465, otherwise smtp, which switches to TLS when the server offers it. |
MAIL_HOST, MAIL_PORT | with smtp | Mail server and port (default 587). |
MAIL_USERNAME, MAIL_PASSWORD | with smtp | Login at the mail server, if it needs one. |
MAIL_FROM_ADDRESS, MAIL_FROM_NAME | no | Sender of every mail, default werkbuch@example.com and werkbuch. |
ATTACHMENTS_MAX_MB | no | Largest upload in MB, default 25. PHP and nginx in the image take 30 and 32 MB: a larger value has no effect beyond that, the upload ends in 413 first (the log of the web service warns at the start). Larger uploads need those limits raised too, see Operations. |
NOTIFICATION_MAIL_DELAY | no | Minutes until the notifications of a work item go out in one mail, default 5. |
WEBHOOKS_ALLOW_PRIVATE | no | true lets webhooks reach private networks (10.x, 172.16.x, 192.168.x, localhost and the like); addresses of cloud metadata services and link-local stay blocked. Default false. See Webhooks. |
API_RATE_LIMIT | no | Requests a minute of the REST API per token or, without a token, per IP address. Default 600. |
API_SESSION_RATE_LIMIT | no | Requests a minute of the REST API per signed-in browser session. Default 3000. |
MCP_RATE_LIMIT | no | Requests a minute of the MCP server per token or per IP address. Default 300. |
Only these variables reach the containers: the compose file passes them on. Anything else goes into the environment of a service, best in a docker-compose.override.yml (see Requirements). Never set a variable that starts with PHP_, NGINX_, SSL_, LOG_, APACHE_, HEALTHCHECK_PATH or TRUSTED_PROXY to an empty value there: the start script of the base image then stops the web service.
The address the browser uses for the live updates comes from APP_URL (host, port and wss:// for https://). REVERB_PUBLIC_HOST, REVERB_PUBLIC_PORT and REVERB_PUBLIC_SCHEME set another one; they are only needed when the browser does not reach Reverb under APP_URL, which with the stack and a proxy in front never happens. They are not in .env: add them to the environment of werkbuch if you need them.
Start
docker compose up -d
docker compose logs -f werkbuch # wait for "werkbuch: ready", then Ctrl+Cdocker compose up -d returns once werkbuch is healthy, because the workers wait for it; on the first start that can take a few minutes. With --wait it returns only when every service is healthy. Then open APP_URL and sign in with ADMIN_EMAIL and ADMIN_PASSWORD.
On every start the web service:
- stops if
DB_PASSWORDorMEILISEARCH_KEYis stillchange-me, - takes
APP_KEY,REVERB_APP_KEYandREVERB_APP_SECRETfrom the environment, else from the data volume, else makes them once and writes them there (werkbuch: generated APP_KEY in storage/app/.app-key (data volume)), - waits up to 60 seconds for the database; if it is not reachable, it stops with
werkbuch: database mariadb:3306 not reachable after 60sand Docker starts it again, - migrates the database,
- creates the first admin from
ADMIN_EMAILandADMIN_PASSWORDwhile werkbuch has no account, - sends the settings of the search indexes to Meilisearch and fills the index when it is empty or lacks fields of this version,
- builds its caches (configuration with the keys, routes, views, events),
- builds the OpenAPI document and warns when
ATTACHMENTS_MAX_MBis larger than PHP takes, - logs
werkbuch: readyand starts nginx and PHP-FPM.
A step that fails stops the container with a message, so a half-migrated instance never serves requests. Meilisearch has to be healthy before the web service starts. The workers, the scheduler and Reverb start once the web service is healthy, read the keys from the data volume, build only their caches and log werkbuch: ready: php artisan …; they never migrate.
werkbuch: no account yet, set ADMIN_EMAIL and ADMIN_PASSWORD and run docker compose up -d means: there is no account yet, and none was created because ADMIN_PASSWORD is empty. Set it in .env and run docker compose up -d again. Once an account exists, every start leaves the accounts alone and ends its line with ADMIN_EMAIL and ADMIN_PASSWORD are only used on the first start., with or without ADMIN_PASSWORD.
Passwords
ADMIN_PASSWORD is only needed for the first start. Once you have signed in, delete the line from .env and run docker compose up -d, so the password no longer sits in the file and in the environment of the container. In the standalone file, put change-me back instead (see Quick start).
Everyone changes their own password, and sets up a second factor, under Personal settings → Security. A forgotten password is reset on the server; the command asks for the new one twice without showing it:
docker compose exec werkbuch php artisan app:reset-password admin@example.comWithout a terminal it reads the first line of its input instead, e.g. docker compose exec -T werkbuch php artisan app:reset-password admin@example.com < new-password.txt. The password is never an argument, so it does not end up in the shell history. Resetting signs the account out everywhere; its API tokens stay valid.
Someone who lost both the authenticator app and the recovery codes gets the second factor turned off; they then sign in with the password alone and can set it up again:
docker compose exec werkbuch php artisan app:reset-two-factor admin@example.comServices
| Service | Does | Networks | Health check |
|---|---|---|---|
werkbuch | nginx and PHP-FPM on port 8080, published as 7740; migrates on start, forwards /app/ (the WebSocket) to Reverb | default, backend | /up for the host of APP_URL |
reverb | the WebSocket server of the live updates on port 6001 | backend | /up on port 6001 |
queue | worker for the queues mail, default, live, notifications, bulk: invitations and password resets, events, live updates, notification mails, deleting projects | default, backend | the worker process runs |
queue-index | worker for search and media: the search index and the previews of pictures | default, backend | the worker process runs |
queue-webhooks | worker for webhooks: the deliveries | default, backend | the worker process runs |
scheduler | starts the scheduled work: notification mails, reminders, templates, the nightly automations, clean-up | default, backend | the scheduler process runs |
mariadb | the database, started with --max-allowed-packet=64M | backend | MariaDB answers and InnoDB is ready |
meilisearch | the search | backend | /health |
backend is an internal network: no published port and no way out to the internet. MariaDB, Meilisearch and Reverb are only in there. The web service is the only one with a published port; the workers and the scheduler are in default too, because they send mails and webhooks.
Search and previews have a worker of their own, queue-index, so they don't wait behind the events of every change; webhooks have one, queue-webhooks, because a receiver that hangs holds its worker for up to 17 seconds per attempt. Run exactly one queue-index, never scale it.
All werkbuch containers run as www-data with no-new-privileges; the code in the image is read-only for them.
What lives where
| What | Where |
|---|---|
Attachments and their previews, pictures of the organization, accounts and projects, and the keys .app-key, .reverb-app-key, .reverb-app-secret | volume werkbuch-data (/var/www/html/storage/app in the containers; Reverb mounts it read-only) |
| Database: projects, work items, wiki, everything else, sessions and the queues | volume mariadb-data |
| Search index | volume meili-data; werkbuch rebuilds it from the database on the next start when it is empty |
| Settings | .env next to docker-compose.yml, or the block at the top of the standalone file |
| Logs | none on disk: docker compose logs |
Containers can be recreated at any time, the volumes stay. docker compose down -v deletes them, and with them the database, every upload and the keys.
.app-key belongs in every backup and must never get lost. APP_KEY encrypts the secrets of the webhooks and the second factors with their recovery codes: with another key, everyone with a second factor is locked out, and every webhook needs a new secret. Never change APP_KEY later. If you set it in .env, set it before the first start; on an instance that already has .app-key, leave it empty. An APP_KEY in .env wins over .app-key; when the two differ, every start warns with werkbuch: APP_KEY of the environment differs from storage/app/.app-key. The Reverb keys are less critical: new ones only need a reload of the open tabs.
Your own MariaDB
To use an existing MariaDB 11.4 instead of the mariadb service, edit docker-compose.yml:
- Remove the service
mariadband the entrymariadbunderdepends_onofwerkbuch. - Add
DB_HOST,DB_PORT,DB_DATABASEandDB_USERNAMEto the blockx-werkbuch-environment(defaultsmariadb,3306,werkbuch,werkbuch);DB_PASSWORDis there already.DB_WAIT_TIMEOUTsets how many seconds the start waits for it (default 60). - Give the user all privileges on its database.
- Set
max_allowed_packetto at least64Min the configuration of that server, like the stack. The largest statements of werkbuch write the webhook deliveries of an event, in chunks of up to 8 MiB (one body of up to 1 MiB per webhook); the default of 16 MiB leaves little room above that.
The database has to be reachable from the network default of the stack.
Storage
Uploads are stored in the volume werkbuch-data only. S3 or another object storage is not supported in this version; plan the disk for your attachments and back up the volume.
Versions
latest follows every release. Pin a version with WERKBUCH_IMAGE in .env, as a tag such as WERKBUCH_IMAGE=baeroe/werkbuch:0.1.0 or, to be sure the image never changes under the tag, with its digest: WERKBUCH_IMAGE=baeroe/werkbuch:0.1.0@sha256:… (docker buildx imagetools inspect baeroe/werkbuch:0.1.0 shows it). Then docker compose pull fetches only what you chose. In the standalone file, change the line image: instead.
docker-compose.yml
The complete compose file, the same one curl downloads above from the main branch. Usually you leave it as it is: everything you set goes into .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: