Install Docmost using Docker on AlmaLinux 9 to run a collaborative wiki with PostgreSQL, Redis, and automatic HTTPS. This guide takes about 15 minutes on a fresh VPS and leaves Docmost’s application port private behind Caddy.
Prerequisites
- A 64-bit AlmaLinux 9 server with at least 2 GB of RAM and 10 GB of free disk space. Increase those resources if you expect a large team or many file uploads.
- SSH access as
root, or a regular Linux account with workingsudoprivileges. - A domain such as
YOUR_DOMAINwith an A record pointing toSERVER_IP. Caddy needs the hostname to request a trusted TLS certificate. - Inbound TCP 80 and 443 allowed in both the VPS provider firewall and the host firewall. Port 3000 will remain bound to loopback.
- A VPSLake Linux VPS if you need an AlmaLinux server with root access.
The commands below assume a non-root SSH account, so they use sudo. If you are logged in as root, omit sudo.
Step 1: Confirm AlmaLinux 9 and update the host
Why: Confirming the release and CPU architecture prevents an Enterprise Linux repository mismatch before Docker is installed.
. /etc/os-release
printf '%s\n' "$PRETTY_NAME"
uname -m
sudo dnf upgrade -y
The release should identify AlmaLinux 9, and the architecture should be x86_64 or aarch64:
AlmaLinux 9.x (...)
x86_64
The minor release and kernel details change as AlmaLinux publishes updates. If DNF reports a mirror, DNS, or signature problem, correct that first instead of continuing with a partial upgrade.
Step 2: Install Docker Engine and Compose
Why: Docker Engine runs the containers, while the Compose plugin manages Docmost and its PostgreSQL, Redis, and Caddy services as one stack.
On a fresh VPS, remove packages that can conflict with Docker’s runtime. Skip this removal if the machine already hosts important Podman containers; inspect those workloads before changing the runtime.
sudo dnf remove -y docker \
docker-client docker-client-latest docker-common docker-latest \
docker-latest-logrotate docker-logrotate docker-engine podman runc
sudo dnf install -y dnf-plugins-core ca-certificates curl openssl
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
sudo dnf makecache
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
This uses Docker’s RHEL repository method documented in the official Docker Engine installation guide, which is the appropriate package path for AlmaLinux 9. Check the daemon, Compose plugin, and a disposable test 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 resembles this; exact versions will change:
active
Client 29.x.y / Server 29.x.y
Docker Compose version v2.x.y
Hello from Docker!
Do not add your account to the docker group unless you deliberately accept its root-equivalent access. Using sudo docker keeps that privilege explicit.
Step 3: Create the Docmost secrets
Why: Docmost needs a persistent application secret, and PostgreSQL must use the same database password in both the database service and the application connection string.
Generate values that contain only hexadecimal characters, so they can safely appear in the database URL. Then create a directory for the deployment:
openssl rand -hex 32
openssl rand -hex 24
sudo install -d -m 0750 /opt/docmost
cd /opt/docmost
sudo vi .env
Create /opt/docmost/.env in vi. Replace the uppercase placeholders with the two generated values and the domain that will serve Docmost:
APP_URL=https://YOUR_DOMAIN
APP_SECRET=REPLACE_WITH_64_HEX_CHARACTERS
DB_PASSWORD=REPLACE_WITH_48_HEX_CHARACTERS
Save the file and lock it down because it contains a database credential:
sudo chmod 600 /opt/docmost/.env
sudo chown root:root /opt/docmost/.env
APP_SECRET must be at least 32 characters; the command above creates 64. APP_URL must match the HTTPS address users will enter, including the subdomain if you use one.
Step 4: Define Docmost and Caddy
Why: Caddy provides HTTPS and forwards WebSocket connections for real-time editing, while Docker’s named volumes keep pages, uploads, and database data after container recreation.
First create the reverse-proxy configuration. The Docmost reverse-proxy documentation explains why WebSocket forwarding is required for collaborative editing.
sudo vi /opt/docmost/Caddyfile
Paste this content, changing YOUR_DOMAIN to the same hostname used in .env:
YOUR_DOMAIN {
reverse_proxy docmost:3000
}
Now create the Compose file:
sudo vi /opt/docmost/docker-compose.yml
Use this configuration. It follows Docmost’s current Docker service layout and keeps the app’s published port on 127.0.0.1 rather than exposing port 3000 to the internet.
services:
caddy:
image: caddy:2
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro,Z
- 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 :Z suffix lets Docker apply an SELinux label to the Caddy bind mount without disabling SELinux. The named volumes are the persistent data boundary: do not remove them when troubleshooting a live installation.
Step 5: Open the web ports and start the stack
Why: firewalld should expose only Caddy’s HTTP and HTTPS endpoints; PostgreSQL, Redis, and Docmost stay on Docker’s internal network or loopback.
Install and enable firewalld, then allow the two ports Caddy needs for web traffic and certificate issuance:
sudo dnf install -y firewalld
sudo systemctl enable --now firewalld
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload
sudo firewall-cmd --list-services
The last command should include http and https. Confirm the Compose file and its environment substitutions before pulling images:
cd /opt/docmost
sudo docker compose config --quiet
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
config --quiet is silent when the YAML is valid. After the first image download, all four services should report Up in output similar to this:
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
Compose may choose different container names. A service that repeatedly restarts needs its logs checked before you proceed.
Verify the Docmost installation
Why: Testing the health endpoint through the domain checks DNS, Caddy’s certificate, the reverse proxy, and Docmost’s HTTP listener together.
Run the check from the server or another machine with DNS access:
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 setup page should appear. Enter a workspace name, administrator name, email address, and a strong unique password, then create the workspace and a test page. Creating a page with an attachment is a useful check that both the editor and the storage volume work.
For a final service check, review recent logs without following them indefinitely:
cd /opt/docmost
sudo docker compose logs --tail=40 caddy docmost db redis
The output should not show a repeating restart loop, a PostgreSQL authentication failure, or an ACME certificate error.
Troubleshooting
No match for argument: docker-ce
DNF cannot see Docker’s repository, often because the repository command was skipped or metadata is stale. Confirm that the host is AlmaLinux 9, then refresh the repository and try the package install again:
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
sudo dnf clean all
sudo dnf makecache
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Caddy logs permission denied for Caddyfile
On an SELinux-enabled AlmaLinux host, the bind-mounted file needs a container-readable label. Check that the Compose mount ends in :ro,Z, then recreate only Caddy so Docker reapplies the label:
cd /opt/docmost
sudo docker compose up -d --force-recreate caddy
sudo docker compose logs --tail=40 caddy
Do not disable SELinux to work around this error.
The browser shows 502 Bad Gateway
Caddy is reachable, but Docmost may still be initializing or the application container may have exited. Inspect the service state and the first error in the dependency logs, fix that error, and restart the stack:
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 still resolve to another address, or port 80/443 may be blocked by the provider firewall or an upstream security group. Confirm that YOUR_DOMAIN resolves to SERVER_IP, run sudo firewall-cmd --list-services, and allow HTTP and HTTPS in every network firewall in front of the VPS.
password authentication failed for user "docmost"
PostgreSQL keeps the password it received when its volume was initialized. Restore the original DB_PASSWORD in .env if it was changed after first startup; do not run docker compose down -v on a live workspace because deleting the database volume destroys stored data.
Hardening and maintenance
- Keep
127.0.0.1:3000in the Compose mapping and never publish PostgreSQL or Redis ports. - Back up the
docmost,db_data,redis_data,caddy_data, andcaddy_configvolumes before upgrades or host maintenance. - Review image changes before applying them. From
/opt/docmost, usesudo docker compose pullfollowed bysudo docker compose up -dfor a planned update. - After confirming Docmost works, tighten SSH access with the VPSLake SSH hardening generator and keep
.envreadable only byroot.
FAQ
Can I use a subdomain for Docmost?
Yes. Point the subdomain’s A record to the VPS, then use that exact hostname in both APP_URL and Caddyfile. Caddy will request the certificate for the subdomain once DNS and inbound web ports are ready.
Why does the setup use PostgreSQL and Redis instead of SQLite?
Docmost’s standard Docker deployment expects PostgreSQL for application data and Redis for supporting real-time and cache operations. Keeping those services in the Compose network avoids exposing database ports while preserving their data in named volumes.
Is port 3000 supposed to be reachable from the internet?
No. The 127.0.0.1:3000:3000 mapping makes Docmost available to Caddy on the server while preventing direct remote access to the application port. Public requests should arrive at HTTPS on port 443.
How do I stop Docmost without deleting its data?
Run sudo docker compose stop from /opt/docmost. This stops the containers but keeps the named volumes; sudo docker compose start brings the same deployment back without repeating workspace setup.