This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.
What Wiki.js does and what it needs
Wiki.js is a Node.js wiki engine with a Markdown editor, Git sync, granular ACLs, and a plugin system for auth and storage. It is not a single-binary app: it needs PostgreSQL 17 or 18 with the ltree and pg_trgm extensions available, and it must be served from a dedicated hostname — sub-folder installs like https://example.com/wiki/ are explicitly unsupported.
The official Docker image bundles Node.js 26 and every extension, so you do not install Node yourself. The image is large (~850 MB) and the upstream docs recommend at least 1 GB RAM on Linux and 1 GB of disk for the app itself, separate from your content. CPU: one core works, two or more lets the background workers (search index, page render, webhooks) keep up.
Outbound access to api.github.com, github.com, and api.iconify.design on 443 is required for update checks, locales, and icon sets. If you run a default-deny firewall, allowlist those.
Prerequisites, ports, and volume constraints
- A Linux host with Docker Engine 24+ and the Compose v2 plugin.
- A DNS A/AAAA record for a dedicated hostname, e.g.
wiki.example.com. - Port 3000 is Wiki.js's HTTP/WebSocket listener. In this setup it binds to
127.0.0.1:3000only, so a reverse proxy on the same host terminates TLS. - Two named volumes:
wiki_dbfor PostgreSQL data andwiki_datafor Wiki.js uploads and local state. Do not mount host paths for these. - PostgreSQL must be reachable as an empty database with a dedicated user. The official
postgresimage already shipsltreeandpg_trgm.
If you want to test without a domain, either SSH-tunnel (ssh -L 3000:127.0.0.1:3000 user@host) or temporarily change the port mapping to 3000:3000 and open the firewall for your IP only. Revert before going live.
Production Docker Compose setup
Create the project directory and the environment file. Generate real secrets — do not reuse examples.
mkdir -p /opt/wikijs && cd /opt/wikijs cat <<'EOF' > .env DB_USER=wikijs DB_PASSWORD=REPLACE_ME DB_NAME=wikijs TZ=UTC EOF # Fill in strong values sed -i "s|REPLACE_ME|$(openssl rand -hex 32)|" .env chmod 600 .env Now write the Compose file. The database is not exposed to the host; only Wiki.js is, and only on loopback.
cat <<'EOF' > compose.yml services: db: image: postgres:17-alpine restart: unless-stopped environment: POSTGRES_DB: ${DB_NAME:-wikijs} POSTGRES_USER: ${DB_USER:-wikijs} POSTGRES_PASSWORD: ${DB_PASSWORD} TZ: ${TZ:-UTC} volumes: - wiki_db:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-wikijs} -d ${DB_NAME:-wikijs}"] interval: 10s timeout: 5s retries: 10 wiki: image: requarks/wiki:2 restart: unless-stopped depends_on: db: condition: service_healthy environment: DB_TYPE: postgres DB_HOST: db DB_PORT: 5432 DB_USER: ${DB_USER:-wikijs} DB_PASS: ${DB_PASSWORD} DB_NAME: ${DB_NAME:-wikijs} TZ: ${TZ:-UTC} ports: - "127.0.0.1:3000:3000" volumes: - wiki_data:/wiki/data volumes: wiki_db: wiki_data: EOF docker compose up -d docker compose logs -f wiki Wait for HTTP Server listening on port 3000. Then open http://127.0.0.1:3000 via SSH tunnel to complete the setup wizard. The wizard asks for the database host, user, and password — use db, wikijs, and the value in .env. It also asks for the site URL; enter the final https://wiki.example.com even if you are currently on localhost, because auth callbacks are built from it.
Reverse proxy, HTTPS, and first-run hardening
Wiki.js needs three things from the proxy: X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-For headers, plus WebSocket upgrades for real-time collaboration on /_collab. It also needs a body size limit at least as large as the wiki's uploadMaxFileSize (10 MB by default).
Example Caddyfile on the same host:
wiki.example.com { encode zstd gzip request_body { max_size 10MB } reverse_proxy 127.0.0.1:3000 { header_up X-Forwarded-Proto {scheme} header_up X-Forwarded-Host {host} header_up X-Forwarded-For {remote_host} } } Caddy handles WebSocket upgrades automatically. If you use Nginx instead, set proxy_http_version 1.1, Upgrade $http_upgrade, Connection $connection_upgrade, and proxy_read_timeout 3600s as shown in the upstream docs.
After the first admin account exists, go to Administration Area → Security and enable Trust X-Forwarded-* Proxy Headers. Without it, rate limiting, audit logs, and live collaboration misbehave behind a proxy. Then close the setup wizard path: the wizard is only reachable while no admin exists, but you should still verify that http://<public-ip>:3000 is not reachable from outside — the loopback bind in Compose prevents that.
Updating, backups, and common pitfalls
Update the app and database together, in that order:
cd /opt/wikijs docker compose pull docker compose up -d docker compose logs -f wiki Back up the database and uploads. Both volumes are named in compose.yml:
docker compose exec -T db pg_dump -U wikijs wikijs | gzip > wikijs-$(date +%F).sql.gz docker run --rm -v wikijs_wiki_data:/data -v "$PWD":/backup alpine \ tar czf /backup/wikijs-data-$(date +%F).tar.gz -C /data . Restore by piping the dump back into psql and extracting the tarball into the wiki_data volume.
Two pitfalls that bite people:
- Sub-folder installs. Wiki.js refuses to run under
/wiki/on an existing domain. If you point the proxy at a path prefix, auth redirects and asset URLs break. Use a dedicated hostname. - Missing
ltree/pg_trgm. If you swap in a non-official Postgres image or a managed database without those extensions, the setup wizard fails with a cryptic migration error. The officialpostgresimage includes them; verify withSELECT * FROM pg_available_extensions WHERE name IN ('ltree','pg_trgm');.
Also watch the outbound allowlist. A firewall that blocks api.github.com silently disables update checks, and blocking api.iconify.design leaves the icon picker empty.
Measured in our sandbox run: total memory 128.4 MB (sum of per-container peaks over a 30s idle window after startup) across 2 containers; largest container 89.0 MB; published port(s) 3000; HTTP probe returned 200. The run took 92.0s including the image download. Required secret(s) DB_PASSWORD were generated for the test run, as the tutorial instructs. Container breakdown: wiki 89.0 MB, db 39.4 MB.
Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.
Originally published with full interactive benchmark metrics and server sizing notes at https://vpsfolio.pages.dev/wikijs-docker-compose-postgresql/.