Wiki.js Installation: Deploy a Modern Collaborative Knowledge Base in Docker

System Requirements & Directory Structure

To deploy a reliable and high-performing instance of Wiki.js, your virtual private server (VPS) should meet the following minimum resource allocations:

• CPU: 1 vCPU (2 vCPUs recommended for larger teams)
• Memory: 1.5 GB RAM (Wiki.js and PostgreSQL together require a minimum of 1 GB RAM to run comfortably without OOM crashes)
• Storage: 10 GB of SSD storage (subject to your documentation volume and asset attachments)
• OS: Ubuntu 22.04 LTS or any modern Linux distribution with Docker Engine and Compose plugin installed.

Before deploying the containers, establish a standardized directory layout under /opt to store application state, configuration files, and database schemas. Execute the following commands on your VPS host to initialize the storage structure:

sudo mkdir -p /opt/wikijs/data
sudo mkdir -p /opt/wikijs/db
sudo mkdir -p /opt/wikijs/nginx
sudo chmod -R 750 /opt/wikijs

Using /opt/wikijs keeps all project assets self-contained, easing future migrations and snapshot-based backups.

Production Docker Compose Configuration

Create a docker-compose.yml file within /opt/wikijs/. This configuration defines two service containers: the Wiki.js application engine and a PostgreSQL database. It utilizes container health checks to prevent race conditions during startup, sets container-level resource limits, and configures restart policies.

Write the following configuration to /opt/wikijs/docker-compose.yml:

version: '3.8'

services:
  db:
    image: postgres:15-alpine
    container_name: wikijs-db
    environment:
      POSTGRES_DB: wikijs
      POSTGRES_USER: wikijs_admin
      # Replace with a secure, random alphanumeric string
      POSTGRES_PASSWORD: xidWOc5MpmBR8J0qZoG4XFw0
    volumes:
      - /opt/wikijs/db:/var/lib/postgresql/data
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          memory: 256M
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U wikijs_admin -d wikijs"]
      interval: 10s
      timeout: 5s
      retries: 5

  wiki:
    image: requarks/wiki:2
    container_name: wikijs-app
    depends_on:
      db:
        condition: service_healthy
    environment:
      DB_TYPE: postgres
      DB_HOST: db
      DB_PORT: 5432
      DB_USER: wikijs_admin
      DB_PASS: xidWOc5MpmBR8J0qZoG4XFw0
      DB_NAME: wikijs
      PORT: 3000
    volumes:
      - /opt/wikijs/data:/wiki/data
    ports:
      - "127.0.0.1:3000:3000"
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '1.5'
          memory: 1024M
        reservations:
          memory: 512M

Key Architectural Details in the Configuration

• Database Pinning: The image postgres:15-alpine is used rather than latest or postgres:alpine. Pinning major versions prevents unexpected schema discrepancies or migration issues during automated container updates.
• Healthcheck-Driven Startup Sequence: The depends_on instruction uses the service_healthy condition. Wiki.js tries to establish database connections immediately on boot. By delaying the application startup until pg_isready returns success, connection timeouts and container boot-loops are avoided.
• Resource Constraints: The deploy block imposes strict hard-limits on memory consumption. This prevents Node.js memory leaks from consuming host resources and protects PostgreSQL from Out-Of-Memory (OOM) termination.
• Loopback Port Binding: Port 3000 is bound explicitly to the loopback interface (127.0.0.1:3000:3000). This ensures the Wiki.js application container is not exposed directly to the public internet, forcing all client traffic through our reverse proxy.

Reverse Proxy Integration (Nginx & SSL)

For production deployment, a reverse proxy handles SSL termination, manages HTTP/2 negotiation, and routes incoming traffic. Nginx is the standard for this role.

Nginx Virtual Host Configuration

Install Nginx on your VPS host:

sudo apt update && sudo apt install -y nginx

Create a new server configuration block in /etc/nginx/sites-available/wiki.example.com (replace wiki.example.com with your actual domain):

server {
    listen 80;
    listen [::]:80;
    server_name wiki.example.com;

    # Certbot challenge path
    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    # Redirect all HTTP requests to HTTPS
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name wiki.example.com;

    # SSL configuration will be managed and appended by Certbot

    client_max_body_size 100M; # Accommodates large asset/image uploads in Wiki.js

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        # Essential headers for real-time WebSocket connection handling
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Standard client identity tracking headers
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;

        # Buffer tweaks for responsiveness
        proxy_buffering off;
        proxy_connect_timeout 600s;
        proxy_send_timeout 600s;
        proxy_read_timeout 600s;
    }
}

Enable the configuration and reload Nginx:

sudo ln -s /etc/nginx/sites-available/wiki.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Let's Encrypt SSL Certificate Setup

Secure your site using Let's Encrypt. The Certbot tool automates certificate generation and configuration injection into Nginx:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d wiki.example.com

Certbot will automatically verify ownership, generate the certificates, and append the necessary SSL directives directly to your configuration file.

Database Optimization & Backup Strategies

Production services require regular database backups. Implement a secure backup rotation script to prevent data loss.

Automatic Postgres Backup Script

Create a script /opt/wikijs/backup_db.sh on the host system:

#!/bin/bash
BACKUP_DIR="/opt/wikijs/backups"
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
DATABASE_NAME="wikijs"
DB_USER="wikijs_admin"
CONTAINER_NAME="wikijs-db"

mkdir -p "$BACKUP_DIR"

# Perform pg_dump inside the active container
docker exec -t "$CONTAINER_NAME" pg_dump -U "$DB_USER" -d "$DATABASE_NAME" -F c > "$BACKUP_DIR/wiki_db_$TIMESTAMP.dump"

# Delete backups older than 14 days to preserve storage space
find "$BACKUP_DIR" -name "wiki_db_*.dump" -mtime +14 -delete

Make the script executable:

sudo chmod +x /opt/wikijs/backup_db.sh

Configure a system cron job to run this backup nightly. Open the crontab editor:

sudo crontab -e

Add the following entry to execute the backup at 02:00 AM local time daily:

0 2 * * * /bin/bash /opt/wikijs/backup_db.sh > /dev/null 2>&1

Post-Installation Setup & Identity Management

Once Nginx is configured and the containers are running (docker compose up -d), navigate to https://wiki.example.com in your web browser.

1. Administrator Account Creation: Fill in the email address, password, and site URL.
2. Initialize Database: The setup wizard automatically builds the required PostgreSQL schema.
3. Finalize Setup: The portal will redirect to the Wiki.js administration panel.

Securing the Wiki

Immediately after setup, review these key configurations to protect your workspace:

1. Disable Open Registration: Navigate to Administration -> Modules -> Authentication. Disable local registrations to prevent unauthorized users from registering accounts.
2. Configure External Identity Providers (IdPs): Under Modules -> Authentication, add a provider:
   • OAuth2 / OpenID Connect (OIDC): Ideal for integrating with identity systems like Keycloak, Authentik, or Okta.
   • GitHub / Google OAuth: Useful for developer wikis. Set the Redirect URI in the GitHub Developer Settings to https://wiki.example.com/login/github/callback.
3. Storage Backends: Under Administration -> Storage, enable the Git storage module. This automatically pushes markdown files of your wiki pages to a private GitHub/GitLab repository on every change, serving as a real-time code-readable backup.