DEV Community

konsongong
konsongong

Posted on Originally published at vpsfolio.pages.dev

Self-Host Wiki.js with Docker Compose and PostgreSQL

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:3000 only, so a reverse proxy on the same host terminates TLS.
  • Two named volumes: wiki_db for PostgreSQL data and wiki_data for 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 postgres image already ships ltree and pg_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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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}
    }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 .
Enter fullscreen mode Exit fullscreen mode

Restore by piping the dump back into psql and extracting the tarball into the wiki_data volume.

Two pitfalls that bite people:

  1. 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.
  2. 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 official postgres image includes them; verify with SELECT * 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/.

Top comments (0)