Install Docmost using Docker on Ubuntu 22.04 to get a private collaborative wiki behind automatic HTTPS. With DNS already pointed to your VPS, the setup takes about 15 minutes and ends at Docmost’s workspace creation screen.
Prerequisites
- A 64-bit Ubuntu 22.04 LTS (Jammy Jellyfish) VPS with at least 2 GB of RAM and 10 GB of free disk space. Plan for extra storage if your team will upload files.
- SSH access as
rootor a normal user with workingsudoprivileges. - A hostname such as
YOUR_DOMAINwith an A record pointing toSERVER_IP. Caddy needs the hostname to issue a trusted TLS certificate. - Inbound TCP 80 and 443 allowed by your VPS provider. SSH must also be reachable; Docmost’s application port will not be public.
- A VPSLake Linux VPS if you need an Ubuntu server with root access.
The commands below use sudo for a regular SSH account. If you are logged in as root, remove sudo from each command.
Step 1: Confirm Ubuntu 22.04 and update the host
Why: Confirming the Jammy codename before adding Docker’s repository prevents Apt from pulling packages for the wrong Ubuntu release.
. /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 check should show Jammy and a 64-bit architecture:
Ubuntu 22.04.x LTS
Codename: jammy
x86_64
Resolve any DNS, mirror, or package-signature error now. Do not substitute noble or another codename in the Docker source.
Step 2: Install Docker Engine and Compose
Why: Docker provides the container runtime, while the Compose plugin starts Docmost, PostgreSQL, Redis, and Caddy from one definition.
Remove packages that can conflict with Docker’s official Engine packages. On a server already running important containers, inspect those workloads before removing a runtime package.
sudo apt-get remove -y docker.io docker-compose docker-compose-v2 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/ubuntu/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/ubuntu
Suites: ${UBUNTU_CODENAME:-$VERSION_CODENAME}
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 Docker’s official Ubuntu installation instructions and avoids the deprecated apt-key workflow. Check the daemon, Compose plugin, and a disposable container:
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; exact patch versions will change:
active
Client 29.x.y / Server 29.x.y
Docker Compose version v2.x.y
Hello from Docker!
This guide keeps sudo docker in use. Membership in the docker group provides root-equivalent control of the host, so add it only if you accept that tradeoff.
Step 3: Create Docmost’s secrets
Why: A long application secret protects sessions, and one shared database password lets both PostgreSQL and Docmost authenticate consistently.
Create the application directory and generate hexadecimal values. Hex characters avoid special-character parsing problems inside the PostgreSQL connection URL.
openssl rand -hex 32
openssl rand -hex 24
sudo install -d -m 0755 /opt/docmost
sudo nano /opt/docmost/.env
Put the first generated value in APP_SECRET, the second in DB_PASSWORD, and use the real hostname in APP_URL:
APP_URL=https://YOUR_DOMAIN
APP_SECRET=REPLACE_WITH_64_HEX_CHARACTERS
DB_PASSWORD=REPLACE_WITH_48_HEX_CHARACTERS
Save the file, then limit access to the credentials:
sudo chmod 600 /opt/docmost/.env
sudo chown root:root /opt/docmost/.env
The first command produces a 64-character secret, which is longer than Docmost’s 32-character minimum. Keep APP_URL identical to the address users will open, including a subdomain if you use one.
Step 4: Define Caddy and the Docmost stack
Why: Caddy obtains and renews HTTPS certificates and forwards WebSocket traffic, while named Docker volumes keep pages, uploads, database records, and certificates across container updates.
Create the reverse-proxy file. The official Docmost Caddy configuration proxies to the Compose service name and supports the collaborative editor:
sudo nano /opt/docmost/Caddyfile
Enter this, replacing YOUR_DOMAIN with the same hostname used in .env:
YOUR_DOMAIN {
reverse_proxy docmost:3000
}
Now create the Compose file:
sudo nano /opt/docmost/docker-compose.yml
Paste the following definition:
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 prevents direct internet access to port 3000; Caddy still reaches Docmost over the private Compose network. Do not publish PostgreSQL or Redis. The quoted variables are loaded from /opt/docmost/.env when Compose runs in that directory.
Step 5: Configure UFW and launch Docmost
Why: UFW should allow only administration and Caddy’s web traffic, leaving the application, database, and cache off the public interface.
If SSH uses a custom port, replace OpenSSH with that port rule before enabling the firewall. Adding the SSH rule first helps prevent locking yourself out.
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
The status should show SSH, HTTP, and HTTPS as allowed. Docker warns that published container ports can bypass some UFW paths, which is another reason this stack publishes only Caddy’s ports and binds Docmost to loopback. Apply the same 80/443 policy in the VPS provider firewall.
Validate the Compose interpolation, download the images, and start the services:
cd /opt/docmost
sudo docker compose config --quiet
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
docker compose config --quiet should return without an error. A healthy stack has four services running, with only Caddy showing public bindings:
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
Names may vary with the Compose project name. A service that repeatedly restarts needs its logs checked before you continue.
Verify the Docmost installation
Why: One HTTPS request checks DNS, the provider firewall, UFW, Caddy’s certificate, the reverse proxy, and Docmost’s listener 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 setup page should ask for a workspace name and administrator account. Use a unique, strong password, create a page, and edit it from a second browser tab to confirm the application and real-time connection are working.
Review recent logs after the first launch:
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 was not added correctly, or Apt is using a stale package index. Confirm that /etc/apt/sources.list.d/docker.sources contains Suites: jammy, then run sudo apt-get update and retry the install. Do not mix a Debian source or Ubuntu 24.04 codename into this server.
UFW blocks SSH after it is enabled
The SSH service rule may not match a custom SSH port. From an existing console or provider VNC session, allow the actual port, for example sudo ufw allow 2222/tcp, then run sudo ufw reload. Keep the current SSH session open until a new connection succeeds.
502 Bad Gateway from Caddy
Docmost may still be starting, or the application container may be restarting because a variable is missing. Run sudo docker compose ps and sudo docker compose logs --tail=80 docmost; check that .env is in /opt/docmost and that sudo docker compose config renders non-empty APP_SECRET, DB_PASSWORD, and APP_URL values.
Caddy cannot obtain a certificate
The A record may point somewhere else, or port 80/443 may be blocked before traffic reaches the VPS. Check that YOUR_DOMAIN resolves to SERVER_IP, allow both ports in the provider firewall, and inspect sudo docker compose logs caddy. Caddy needs a publicly resolvable hostname for a trusted certificate.
Hardening and maintenance
- Keep
/opt/docmost/.envroot-readable only and do not commit it to a repository. - Back up the
docmost,db_data, andcaddy_datavolumes before upgrades or host maintenance.docker compose downdoes not remove named volumes unless you add-v. - Update the stack deliberately with
sudo docker compose pull && sudo docker compose up -dfrom/opt/docmost, then check the logs and open the workspace. - After confirming SSH access, use the VPSLake SSH hardening generator to review key-only authentication and other SSH settings.
FAQ
Can I use a subdomain for Docmost?
Yes. Create an A record such as docs.YOUR_DOMAIN, then use that exact hostname in both APP_URL and Caddyfile. Caddy will request the certificate for the subdomain once DNS is visible and the web ports are reachable.
Why are PostgreSQL and Redis separate containers?
Docmost uses PostgreSQL for durable application data and Redis for caching and real-time coordination. Keeping both on the private Compose network avoids exposing their ports while allowing the application to reach them by service name.
Can I access Docmost at the server IP?
You can test the application locally with curl http://127.0.0.1:3000, but the public configuration is designed for a domain. A hostname is needed for Caddy’s trusted HTTPS certificate and gives APP_URL a stable value.
What happens if I run docker compose down?
The containers and network stop, but the named volumes remain, so pages, uploads, PostgreSQL data, Redis data, and Caddy certificates are preserved. Start the deployment again with sudo docker compose up -d from /opt/docmost.