2026-11-22 · wiki · docker · postgresql · self-hosting
Self-Host Wiki.js with Docker Compose and PostgreSQL
Run Wiki.js in Docker Compose with PostgreSQL 17, ltree/pg_trgm extensions, WebSocket-ready reverse proxy, and safe first-run setup.
- Total RAM
- 128.4 MB
- Startup
- 92.0 s
- Port
- 3000
- HTTP
- 200
wiki 89.0 MB
· db 39.4 MB
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.