How to Install Docmost with Docker on AlmaLinux 9

Install Docmost using Docker on AlmaLinux 9 with PostgreSQL, Redis, Caddy HTTPS, firewalld, and checks for a working private wiki in minutes.
A polished 3D AlmaLinux server scene with glowing Docker containers and blank documentation panels on a midnight-blue background.

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 working sudo privileges.
  • A domain such as YOUR_DOMAIN with an A record pointing to SERVER_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:3000 in the Compose mapping and never publish PostgreSQL or Redis ports.
  • Back up the docmost, db_data, redis_data, caddy_data, and caddy_config volumes before upgrades or host maintenance.
  • Review image changes before applying them. From /opt/docmost, use sudo docker compose pull followed by sudo docker compose up -d for a planned update.
  • After confirming Docmost works, tighten SSH access with the VPSLake SSH hardening generator and keep .env readable only by root.

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.

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

How to Install Docmost Using Docker on AlmaLinux 8

Next Article

Remote Desktop From Phone: Android and iPhone Setup

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 ✨