How to Install Docmost Using Docker on Debian 12

Install Docmost using Docker on Debian 12 with PostgreSQL, Redis, Caddy HTTPS, UFW rules, health checks, and fixes for a private wiki in minutes.
A polished 3D documentation workspace with glowing container blocks, a database cylinder, and orange-cyan light trails over a midnight-blue server scene.

Install Docmost using Docker on Debian 12 to run a private collaborative wiki behind HTTPS. With DNS already pointed at your VPS, the deployment takes about 15 minutes and ends at the Docmost workspace setup screen.

Prerequisites

  • A 64-bit Debian 12 (Bookworm) VPS with at least 2 GB of RAM and 10 GB of free disk space. Leave additional room for uploaded files and Docker image updates.
  • SSH access as root, or a regular Linux account with working sudo privileges.
  • A domain such as YOUR_DOMAIN with an A record pointing to SERVER_IP. Caddy uses this hostname to obtain and renew a trusted TLS certificate.
  • Inbound TCP ports 80 and 443 allowed by both the VPS provider and the server firewall. Port 3000 does not need to be public.
  • A VPSLake Linux VPS if you need a Debian server with root access.

The commands below use sudo for a normal SSH user. If you are logged in as root, remove sudo from the commands.

Step 1: Confirm Debian 12 and update the server

Why: Checking the release codename first prevents Docker’s Apt repository from being configured for the wrong Debian version.

. /etc/os-release
printf '%s\n' "$PRETTY_NAME"
printf 'Codename: %s\n' "$VERSION_CODENAME"
uname -m
sudo apt-get update
sudo apt-get upgrade -y

The output should identify Bookworm and a supported 64-bit architecture:

Debian GNU/Linux 12 (bookworm)
Codename: bookworm
x86_64

Fix any Apt mirror, DNS, or signature error before continuing. Do not point a Debian 12 machine at a Debian 13 repository to work around a package error.

Step 2: Install Docker Engine and Compose

Why: Docker runs the application containers, and the Compose plugin starts Docmost, PostgreSQL, Redis, and Caddy as one deployment.

On a fresh VPS, remove unofficial or conflicting Docker packages first. If this server already runs containers, inspect them before removing podman-docker, containerd, or runc.

sudo apt-get remove -y docker.io docker-compose docker-doc docker-buildx podman-docker containerd runc
sudo apt-get install -y ca-certificates curl openssl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: bookworm
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker

This follows the signed-key setup in Docker’s official Debian installation guide. Verify the daemon, Compose plugin, and a disposable container before configuring Docmost:

sudo systemctl is-active docker
sudo docker version --format 'Client {{.Client.Version}} / Server {{.Server.Version}}'
sudo docker compose version
sudo docker run --rm hello-world

Expected output is similar to this; the patch versions will change:

active
Client 29.x.y / Server 29.x.y
Docker Compose version v2.x.y
Hello from Docker!

Keep using sudo docker in this guide. Membership in the docker group grants root-equivalent access to the host, so add it only as a deliberate administration choice.

Step 3: Create protected Docmost settings

Why: Docmost needs a persistent application secret, while PostgreSQL must use one matching password in both its container and the application connection string.

Generate hexadecimal values so the database password can safely appear in a connection URL, then create the deployment directory:

openssl rand -hex 32
openssl rand -hex 24
sudo install -d -m 0750 /opt/docmost
sudo nano /opt/docmost/.env

In /opt/docmost/.env, use the first command’s output for APP_SECRET, the second for DB_PASSWORD, and your real hostname for APP_URL:

APP_URL=https://YOUR_DOMAIN
APP_SECRET=REPLACE_WITH_64_HEX_CHARACTERS
DB_PASSWORD=REPLACE_WITH_48_HEX_CHARACTERS

Save the file and restrict it because it contains a database credential:

sudo chmod 600 /opt/docmost/.env
sudo chown root:root /opt/docmost/.env

The secret generated by openssl rand -hex 32 is 64 characters, which exceeds Docmost’s 32-character minimum. APP_URL must exactly match the hostname visitors will use, including a subdomain if you choose one.

Step 4: Add Caddy and the Compose definition

Why: Caddy terminates HTTPS and forwards WebSocket connections for Docmost’s real-time editor, while Docker volumes preserve the wiki when containers are recreated.

Create /opt/docmost/Caddyfile:

sudo nano /opt/docmost/Caddyfile

Enter this content and replace YOUR_DOMAIN with the same hostname used in .env:

YOUR_DOMAIN {
    reverse_proxy docmost:3000
}

The official Docmost Caddy guide uses this service-to-service proxy pattern and confirms that Caddy handles HTTPS and WebSockets. Now create the Compose file:

sudo nano /opt/docmost/docker-compose.yml

Paste the following:

services:
  caddy:
    image: caddy:2
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - docmost
    restart: unless-stopped

  docmost:
    image: docmost/docmost:latest
    depends_on:
      - db
      - redis
    environment:
      APP_URL: "${APP_URL}"
      APP_SECRET: "${APP_SECRET}"
      DATABASE_URL: "postgresql://docmost:${DB_PASSWORD}@db:5432/docmost"
      REDIS_URL: "redis://redis:6379"
    ports:
      - "127.0.0.1:3000:3000"
    restart: unless-stopped
    volumes:
      - docmost:/app/data/storage

  db:
    image: postgres:18
    environment:
      POSTGRES_DB: docmost
      POSTGRES_USER: docmost
      POSTGRES_PASSWORD: "${DB_PASSWORD}"
    restart: unless-stopped
    volumes:
      - db_data:/var/lib/postgresql

  redis:
    image: redis:8
    command: ["redis-server", "--appendonly", "yes", "--maxmemory-policy", "noeviction"]
    restart: unless-stopped
    volumes:
      - redis_data:/data

volumes:
  docmost:
  db_data:
  redis_data:
  caddy_data:
  caddy_config:

The 127.0.0.1 binding keeps direct port 3000 access off the public interface. The named volumes hold pages, uploads, PostgreSQL data, Redis persistence, and Caddy certificates outside the disposable container layers.

Step 5: Allow web traffic and start Docmost

Why: UFW should permit SSH and Caddy’s two web ports while the application, database, and cache remain unpublished.

If SSH uses a custom port, allow that port instead of OpenSSH before enabling UFW:

sudo apt-get install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
sudo ufw status verbose

Docker warns that published container ports can bypass some UFW filtering paths. The safer layout here is to publish only Caddy’s 80 and 443, keep port 3000 on loopback, and apply the same web-port policy in the VPS provider firewall.

Validate the rendered Compose configuration, pull the images, and start the stack:

cd /opt/docmost
sudo docker compose config --quiet
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps

The first pull may take several minutes. A healthy result has four services in an Up state, with Docmost bound only to loopback:

NAME                 SERVICE   STATUS    PORTS
docmost-caddy-1      caddy     Up        0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp
docmost-docmost-1    docmost   Up        127.0.0.1:3000->3000/tcp
docmost-db-1         db        Up
docmost-redis-1      redis     Up

Compose may choose different names. If a service repeatedly restarts, inspect its logs before opening the site.

Verify the Docmost installation

Test the health endpoint through HTTPS so one request checks DNS, Caddy’s certificate, the reverse proxy, and Docmost’s listener:

curl -fsS -o /dev/null -w 'HTTP %{http_code}\n' https://YOUR_DOMAIN/api/health

Expected output:

HTTP 200

Open https://YOUR_DOMAIN in a browser. Docmost should display the workspace setup form. Enter a workspace name, administrator details, and a unique strong password, then create a test page and edit it in a second browser tab to confirm real-time collaboration.

Review recent logs after the first login:

cd /opt/docmost
sudo docker compose logs --tail=40 caddy docmost db redis

The output should not show a repeating restart loop, PostgreSQL authentication failure, or ACME certificate error.

Troubleshooting

Unable to locate package docker-ce

The Docker source is missing, has the wrong suite, or Apt has stale metadata. Confirm that the source uses Debian 12’s bookworm suite, refresh Apt, and retry the package installation:

grep -E '^(URIs|Suites|Architectures|Signed-By):' /etc/apt/sources.list.d/docker.sources
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Do not change bookworm to trixie on a Debian 12 host; mixing release repositories can break the operating system.

The browser shows 502 Bad Gateway

Caddy is reachable, but Docmost may still be starting or may have exited. Inspect the application and dependency logs, correct the first reported error, and restart the services:

cd /opt/docmost
sudo docker compose ps
sudo docker compose logs --tail=80 docmost db redis
sudo docker compose restart

Caddy cannot obtain an HTTPS certificate

The domain may resolve to a different server, or port 80/443 may be blocked by the provider firewall. Confirm that YOUR_DOMAIN resolves to SERVER_IP, allow both ports in the provider controls, and keep Caddy running while it completes the certificate request.

password authentication failed for user "docmost"

PostgreSQL keeps the password from its first initialization. Restore the original DB_PASSWORD in .env if it was changed later; do not run sudo docker compose down -v on a live wiki because removing db_data deletes the database.

Hardening and maintenance

  • Back up the docmost, db_data, redis_data, caddy_data, and caddy_config volumes before upgrades or VPS maintenance.
  • Review image updates before applying them. From /opt/docmost, run sudo docker compose pull and then sudo docker compose up -d, followed by sudo docker compose ps.
  • Keep port 3000, PostgreSQL, and Redis unpublished. After Docmost works, use the VPSLake SSH hardening generator to tighten SSH access.

FAQ

What DNS record does Caddy need?

Create an A record for YOUR_DOMAIN that points to SERVER_IP. Wait until public DNS resolves to that address before starting the stack, because Caddy must reach the server on ports 80 and 443 to issue the certificate.

Can I use an existing Nginx or Apache server instead of Caddy?

Yes, but the proxy must send requests to Docmost on port 3000 and support WebSocket upgrades. Keep APP_URL set to the public HTTPS address and do not expose PostgreSQL or Redis.

Does docker compose down delete my pages?

No. down removes the containers and network but leaves the named volumes. Avoid down -v unless you intentionally want to erase the Docmost, PostgreSQL, Redis, and Caddy data volumes.

How do I change the domain after installation?

Update APP_URL in .env and the hostname in Caddyfile, then run sudo docker compose up -d from /opt/docmost. Caddy will request a certificate for the new hostname after its DNS record points to the VPS.

Samrat Ghosh
Written by

Samrat Ghosh

Founder & Infrastructure Engineer

Samrat Ghosh is the founder of VPSLake, where he builds and runs the remote desktop and VPS hosting infrastructure the company is built on. He writes hands-on guides about RDP, Windows Server, VPS management and secure remote access - the practical documentation he wishes had…

Previous Article

What Is a Bare Metal Server? vs Dedicated, VPS and Cloud

Next Article

Does VPS Location Matter? A Practical Answer

Write a Comment

Leave a Comment

Your email address will not be published. Required fields are marked *

Subscribe to our Newsletter

Subscribe to our email newsletter to get the latest posts delivered right to your email.
Pure inspiration, zero spam ✨