Skip to content

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_on with condition: service_healthy).
  • A machine with amd64 or arm64.
  • 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 example 536870912 for 512 MiB) in the environment of meilisearch.
    • 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=8 in the environment of werkbuch.
    • Four worker containers: three queues and the scheduler.
  • 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.

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

Quick start: paste and deploy ​

One compose file with everything in it, no .env:

  1. Paste the block below into a new stack in Dockge or Portainer, or save it as compose.yaml on your server.
  2. Change the five values at the top: APP_URL (the https address of your reverse proxy), ADMIN_EMAIL, ADMIN_PASSWORD, DB_PASSWORD and MEILISEARCH_KEY. Choose long random values, for example with openssl rand -hex 24; the key of Meilisearch needs at least 16 characters.
  3. Deploy (Dockge, Portainer) or run docker compose up -d. Wait for werkbuch: ready in the logs of werkbuch, then open APP_URL and sign in with ADMIN_EMAIL and ADMIN_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.

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:

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 ​

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 ​

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).

VariableRequiredMeaning
APP_URLyesPublic 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_LOCALEnoen (default) or de: the language of the organization, set when it is created on the first start. Change it later under Settings → General.
WERKBUCH_IMAGEnoDefault baeroe/werkbuch:latest. Pin a version, see Versions.
WERKBUCH_BIND, WERKBUCH_PORTnoHost 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_EMAILyesEmail of the first admin. Compose refuses to start without it, also later; it is only used while werkbuch has no account.
ADMIN_PASSWORDfirst startPassword 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_PASSWORDyesPassword of the database user werkbuch. MariaDB stores it on the first start; changing it in .env afterwards breaks the connection.
DB_ROOT_PASSWORDyesPassword of the MariaDB root user. Root can only log in from inside the mariadb container.
MEILISEARCH_KEYyesMaster 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_KEYnoEncryption 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_SECRETnoKey and secret of the live updates (Reverb). Empty: made on the first start and kept in the data volume.
TRUSTED_PROXIESnoIP 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_MAILERnolog (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_SCHEMEnosmtps 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_PORTwith smtpMail server and port (default 587).
MAIL_USERNAME, MAIL_PASSWORDwith smtpLogin at the mail server, if it needs one.
MAIL_FROM_ADDRESS, MAIL_FROM_NAMEnoSender of every mail, default werkbuch@example.com and werkbuch.
ATTACHMENTS_MAX_MBnoLargest 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_DELAYnoMinutes until the notifications of a work item go out in one mail, default 5.
WEBHOOKS_ALLOW_PRIVATEnotrue 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_LIMITnoRequests a minute of the REST API per token or, without a token, per IP address. Default 600.
API_SESSION_RATE_LIMITnoRequests a minute of the REST API per signed-in browser session. Default 3000.
MCP_RATE_LIMITnoRequests 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 ​

bash
docker compose up -d
docker compose logs -f werkbuch    # wait for "werkbuch: ready", then Ctrl+C

docker 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:

  1. stops if DB_PASSWORD or MEILISEARCH_KEY is still change-me,
  2. takes APP_KEY, REVERB_APP_KEY and REVERB_APP_SECRET from 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)),
  3. waits up to 60 seconds for the database; if it is not reachable, it stops with werkbuch: database mariadb:3306 not reachable after 60s and Docker starts it again,
  4. migrates the database,
  5. creates the first admin from ADMIN_EMAIL and ADMIN_PASSWORD while werkbuch has no account,
  6. sends the settings of the search indexes to Meilisearch and fills the index when it is empty or lacks fields of this version,
  7. builds its caches (configuration with the keys, routes, views, events),
  8. builds the OpenAPI document and warns when ATTACHMENTS_MAX_MB is larger than PHP takes,
  9. logs werkbuch: ready and 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:

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

Without 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:

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

Services ​

ServiceDoesNetworksHealth check
werkbuchnginx and PHP-FPM on port 8080, published as 7740; migrates on start, forwards /app/ (the WebSocket) to Reverbdefault, backend/up for the host of APP_URL
reverbthe WebSocket server of the live updates on port 6001backend/up on port 6001
queueworker for the queues mail, default, live, notifications, bulk: invitations and password resets, events, live updates, notification mails, deleting projectsdefault, backendthe worker process runs
queue-indexworker for search and media: the search index and the previews of picturesdefault, backendthe worker process runs
queue-webhooksworker for webhooks: the deliveriesdefault, backendthe worker process runs
schedulerstarts the scheduled work: notification mails, reminders, templates, the nightly automations, clean-updefault, backendthe scheduler process runs
mariadbthe database, started with --max-allowed-packet=64MbackendMariaDB answers and InnoDB is ready
meilisearchthe searchbackend/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 ​

WhatWhere
Attachments and their previews, pictures of the organization, accounts and projects, and the keys .app-key, .reverb-app-key, .reverb-app-secretvolume 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 queuesvolume mariadb-data
Search indexvolume 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
Logsnone 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:

  1. Remove the service mariadb and the entry mariadb under depends_on of werkbuch.
  2. Add DB_HOST, DB_PORT, DB_DATABASE and DB_USERNAME to the block x-werkbuch-environment (defaults mariadb, 3306, werkbuch, werkbuch); DB_PASSWORD is there already. DB_WAIT_TIMEOUT sets how many seconds the start waits for it (default 60).
  3. Give the user all privileges on its database.
  4. Set max_allowed_packet to at least 64M in 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.

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: