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 workingsudoprivileges. - A domain such as
YOUR_DOMAINwith an A record pointing toSERVER_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, andcaddy_configvolumes before upgrades or VPS maintenance. - Review image updates before applying them. From
/opt/docmost, runsudo docker compose pulland thensudo docker compose up -d, followed bysudo 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.