Install Docmost using Docker on Debian 11 to run a private collaborative wiki with PostgreSQL, Redis, and HTTPS. Allow about 15 minutes for the Docker images, DNS check, and first workspace setup.
Prerequisites
- A 64-bit Debian 11 (Bullseye) VPS with at least 2 GB of RAM and 10 GB of free disk space. Debian 11 reached the end of its Debian LTS period on August 31, 2026, so plan a migration to Debian 12 or newer after this deployment.
- SSH access as
root, or a normal Linux account with workingsudoprivileges. - A domain such as
YOUR_DOMAINwith an A record pointing toSERVER_IP. Caddy needs this name to request a trusted TLS certificate. - Provider-level inbound TCP access for ports 80 and 443. Docmost itself will stay on the server’s private Docker network.
- A VPSLake Linux VPS if you need a Debian server with root access.
This guide uses the Docker Engine repository for Bullseye, Docker Compose, and Debian’s ufw firewall. Run the commands as a sudo-capable user; add sudo to commands if you are not logged in as root.
Step 1: Confirm Debian 11 and update the host
Confirming the codename prevents an old image from accidentally using a Bookworm or Trixie repository.
. /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 release should identify Debian GNU/Linux 11 and the codename should be bullseye. For a typical 64-bit VPS, the architecture line is x86_64:
Debian GNU/Linux 11 (bullseye)
Codename: bullseye
x86_64
If apt-get update reports expired Debian mirrors, repair the provider’s Debian 11 archive sources before continuing. Do not point a Bullseye host at a newer release just to silence an update error.
Step 2: Install Docker Engine and Compose
Docker runs Docmost’s containers, while the Compose plugin manages the application, database, cache, and reverse proxy together. Docker’s Debian installation guide uses a signed keyring and a dedicated Apt source, which avoids the deprecated apt-key approach.
Install the tools needed to add the repository, then register the Bullseye source explicitly:
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: bullseye
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
Check 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; package patch versions will vary:
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 control, so it should be an intentional choice rather than a convenience added during installation.
Step 3: Create Docmost’s secrets and configuration
The application secret signs Docmost data, and PostgreSQL must receive the same database password that appears in the connection URL. Hexadecimal values avoid special-character parsing problems in that URL.
Create the deployment directory and generate two random values:
openssl rand -hex 32
openssl rand -hex 24
sudo install -d -m 0750 /opt/docmost
sudo nano /opt/docmost/.env
Enter this in /opt/docmost/.env, replacing every uppercase placeholder with the matching generated value and your real domain:
APP_URL=https://YOUR_DOMAIN
APP_SECRET=REPLACE_WITH_64_HEX_CHARACTERS
DB_PASSWORD=REPLACE_WITH_48_HEX_CHARACTERS
Save the file, then restrict it because it contains the database credential:
sudo chmod 600 /opt/docmost/.env
sudo chown root:root /opt/docmost/.env
APP_SECRET must be at least 32 characters. APP_URL must exactly match the hostname people will use, including a subdomain such as docs.YOUR_DOMAIN.
Step 4: Define the containers and HTTPS proxy
Docmost’s official deployment uses PostgreSQL 18 and Redis 8. Caddy adds automatic HTTPS and forwards WebSocket connections, which the real-time editor needs; the Docmost reverse-proxy guidance recommends this production pattern.
Create a Caddy configuration that sends requests to the internal docmost service:
sudo nano /opt/docmost/Caddyfile
Use the following content, changing YOUR_DOMAIN to the same hostname in .env:
YOUR_DOMAIN {
reverse_proxy docmost:3000
}
Now create /opt/docmost/docker-compose.yml:
sudo nano /opt/docmost/docker-compose.yml
Paste this Compose file:
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 port 3000 off the public interface, while the named volumes preserve pages, uploads, database records, Redis data, and TLS certificates when containers are recreated.
Step 5: Allow web traffic and start Docmost
Only Caddy needs public access. UFW allows SSH and the two web ports; PostgreSQL and Redis have no published host ports.
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 can place published ports ahead of some UFW filtering paths, so the safest rule is to publish only the ports you actually need. This Compose file exposes only 80 and 443 publicly and binds Docmost to loopback.
Validate the interpolated Compose file, 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 can take several minutes. A healthy result has four services in an Up state, with only Caddy showing public port mappings:
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
docmost-db-1 db Up
docmost-redis-1 redis Up
Container names may differ. A service that repeatedly restarts needs its logs checked before you open the site.
Verify the Docmost installation
Test the health endpoint through the domain so DNS, Caddy’s certificate, the proxy route, and the Docmost listener are checked together:
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. The Docmost workspace form should appear. 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 the real-time path works.
Review the startup messages once the workspace exists:
cd /opt/docmost
sudo docker compose logs --tail=40 caddy docmost db redis
The logs should not contain a restart loop, database 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. Check that the source says Suites: bullseye, then refresh the cache and retry:
grep -E '^(URIs|Suites|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 replace bullseye with bookworm on a Debian 11 system; mixing release repositories can break the host.
permission denied while trying to connect to the Docker daemon socket
The current account is not allowed to use Docker directly. Use the sudo docker and sudo docker compose forms shown here, or deliberately configure Docker group access for a trusted administrator and reconnect the SSH session.
The browser shows 502 Bad Gateway
Caddy is reachable but Docmost is still initializing or has stopped. Inspect the first application or dependency error, then restart only after correcting the cause:
cd /opt/docmost
sudo docker compose ps
sudo docker compose logs --tail=80 docmost db redis
sudo docker compose restart
Caddy cannot obtain a certificate
The domain may point to another address, or port 80/443 may be blocked by the VPS provider firewall. Confirm that YOUR_DOMAIN resolves to SERVER_IP, allow both ports in the provider’s network controls, and keep the Caddy container running while it requests the certificate.
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 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 host maintenance. - Update deliberately from
/opt/docmostwithsudo docker compose pullfollowed bysudo docker compose up -d, and review the result withsudo docker compose ps. - Keep port 3000, PostgreSQL, and Redis unpublished. The VPSLake SSH hardening generator can help tighten SSH after the application is working.
- Treat Debian 11 as a migration target: move the deployment to a supported Debian release before relying on it for a long-lived public workspace.
FAQ
Is Debian 11 still a good choice for a new Docmost server?
No. Debian 11 is a legacy target now that its regular LTS period has ended. Use this guide when an existing Bullseye VPS cannot be upgraded immediately, and choose Debian 12 or newer for a fresh deployment.
Can I access Docmost by IP address instead of a domain?
You can test the app over an IP, but Caddy cannot provide the same straightforward trusted certificate for a normal public deployment. A domain also gives you a stable value for APP_URL and keeps browser WebSocket connections on HTTPS.
Why are PostgreSQL and Redis separate containers?
Docmost uses PostgreSQL for structured application data and Redis for supporting cache and real-time work. Compose keeps both services on its private network, so neither database port is exposed to the internet.
How do I stop Docmost without deleting its data?
From /opt/docmost, run sudo docker compose stop to stop the services while retaining their named volumes. Use sudo docker compose start to bring the same workspace back without repeating setup.