How to Install Docmost Using Docker on AlmaLinux 8

Install Docmost using Docker on AlmaLinux 8 with PostgreSQL, Redis, Caddy HTTPS, firewalld, and checks for a working private wiki in minutes.
A polished 3D server rack beside glowing container modules and a secure database cylinder on a midnight-blue background.

Install Docmost using Docker on AlmaLinux 8 to run a collaborative wiki behind HTTPS on your own VPS. Allow about 15 minutes for the first image download, domain check, and workspace setup.

Prerequisites

  • A 64-bit AlmaLinux 8 VPS with at least 2 GB of RAM and 10 GB of free disk space. More memory is useful if several people will edit pages at once.
  • 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 uses that hostname to request the TLS certificate.
  • Inbound TCP ports 80 and 443 available at both the VPS provider and the server firewall. You do not need to expose port 3000 publicly.
  • A VPSLake Linux VPS with root access if you still need a server for this deployment.

This guide uses the RHEL-compatible Docker repository, DNF, and firewalld. Commands assume a non-root SSH account; if you are already root, omit sudo.

Step 1: Confirm AlmaLinux 8 and update the host

Checking the release and architecture first prevents an EL8 server from accidentally receiving instructions for another distribution.

. /etc/os-release
printf '%s\n' "$PRETTY_NAME"
uname -m
sudo dnf upgrade -y

The release should begin with AlmaLinux 8, and the architecture should be x86_64 or aarch64:

AlmaLinux 8.x (...)
x86_64

The minor version and kernel text can change as AlmaLinux publishes updates. Resolve any repository, DNS, or GPG-signature error before installing Docker.

Step 2: Install Docker Engine and Compose

Docker supplies the container runtime, while the Compose plugin lets you start Docmost and its two dependencies from one file. Docker’s RHEL installation instructions use the same RPM repository approach on maintained EL8 systems.

Remove packages that can conflict with Docker’s runtime on a fresh VPS. This does not remove Docker images or volumes, but do not run it on a host where you still need active Podman workloads.

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

Use sudo for Docker commands throughout this guide. The Docker socket grants root-equivalent control, so there is no need to add your SSH account to the docker group just to complete this setup.

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 checks look similar to this; patch numbers will vary:

active
Client 29.x.y / Server 29.x.y
Docker Compose version v2.x.y
Hello from Docker!

Step 3: Create protected Docmost secrets

Docmost needs an application secret, and PostgreSQL needs a password that is used consistently by both the database container and the application connection string. Hexadecimal values are convenient here because they do not require URL escaping.

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 using this content. Replace the uppercase values with the generated strings and your real hostname.

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 because it contains a database credential:

sudo chmod 600 /opt/docmost/.env

APP_URL must exactly match the URL you will open in the browser. The Docmost installation documentation requires a random secret of at least 32 characters and uses PostgreSQL plus Redis for the standard Docker deployment.

Step 4: Add Caddy and the Compose definition

The reverse proxy terminates HTTPS and forwards requests to Docmost, including WebSocket traffic used by real-time editing. Docmost listens only on loopback, so an internet user cannot bypass Caddy by visiting port 3000.

Create the Caddy configuration:

cd /opt/docmost
sudo vi Caddyfile

Paste the following, replacing YOUR_DOMAIN with the same hostname used in .env:

YOUR_DOMAIN {
    reverse_proxy docmost:3000
}

Now create the Compose file:

sudo vi docker-compose.yml

Use this configuration:

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 mount flag gives the Caddy container an SELinux-compatible label for the local configuration file. It is safer than disabling SELinux, and the named volumes keep pages, uploaded files, database records, Redis data, and certificates outside the container layers.

Step 5: Open firewalld and launch the stack

Only the reverse proxy needs public access. Allowing HTTP as well as HTTPS lets Caddy complete certificate challenges and redirect visitors to the encrypted endpoint.

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 final command should include http and https. Validate the resolved Compose model before downloading several large images, then start the services:

cd /opt/docmost
sudo docker compose config --quiet
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps

config --quiet produces no output when the YAML and .env substitutions are valid. Once startup finishes, the four services should show a running state:

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 keeps restarting needs the logs checked before you continue.

Verify the Docmost installation

Test the health endpoint through the domain rather than only from inside Docker. This single request exercises DNS, Caddy’s certificate, the proxy route, and Docmost’s HTTP 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 show its workspace setup form. Enter a workspace name, administrator name, email address, and a strong unique password, then create the workspace. Create a test page after the dashboard opens so you confirm that the editor and storage volume both work.

Review recent logs after the first login:

cd /opt/docmost
sudo docker compose logs --tail=40 caddy docmost db redis

Normal logs should not contain a repeating restart loop, PostgreSQL authentication failure, or ACME certificate error.

Troubleshooting

No match for argument: docker-ce

The Docker repository was not added or DNF is using stale metadata. Confirm that the host reports AlmaLinux 8 and refresh the repository cache, then repeat the Docker package install:

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 shows permission denied for Caddyfile

SELinux is correctly preventing an unlabeled bind mount from being read. Make sure the Compose entry ends in :ro,Z, then recreate Caddy so Docker applies the label:

cd /opt/docmost
sudo docker compose up -d --force-recreate caddy
sudo docker compose logs --tail=40 caddy

The browser returns 502 Bad Gateway

Caddy is reachable, but Docmost has not finished starting or the application container exited. Check the application and dependency logs, correct the first reported 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 get a certificate

The domain may still point elsewhere, or an upstream security group may block port 80 or 443. Confirm the A record resolves to SERVER_IP, verify firewalld lists both services, and allow the same ports in the VPS provider firewall.

password authentication failed for user "docmost"

PostgreSQL keeps the original password in its named volume. If DB_PASSWORD was changed after the first startup, restore the original value in .env and restart; never use docker compose down -v on a live installation because removing the database volume destroys stored data.

Hardening and maintenance

  • Keep 127.0.0.1:3000 in the Compose port mapping and do not publish PostgreSQL or Redis ports.
  • Back up the docmost, db_data, redis_data, caddy_data, and caddy_config volumes before upgrades or host maintenance.
  • Update deliberately from /opt/docmost with sudo docker compose pull followed by sudo docker compose up -d; review image changes before using them on a production wiki.
  • After confirming the application works, tighten SSH access with the VPSLake SSH hardening generator and keep .env readable only by root.

FAQ

Can Docmost run on an IP address instead of a domain?

It can be tested over an IP if you publish port 3000 and change APP_URL, but that removes Caddy’s automatic trusted certificate. A domain is the practical choice for a public workspace and for secure real-time editing.

Why does this setup include Caddy when Docmost already serves HTTP?

Caddy handles certificate issuance, HTTPS renewal, and the reverse-proxy connection to Docmost. It also leaves the application port private, which reduces the number of internet-facing services on the VPS.

Where are my pages and uploads stored?

Docmost stores application files in the docmost named volume, while PostgreSQL uses db_data. Redis and Caddy use their own volumes, so recreating containers does not by itself remove workspace data or certificate state.

How do I stop the installation without deleting it?

Run sudo docker compose stop from /opt/docmost to stop the containers while retaining their volumes. Use sudo docker compose start to bring the same stack back without re-running the 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

Remote Desktop Keeps Disconnecting? 8 Fixes That Work

Next Article

How to Install Docmost with Docker on AlmaLinux 9

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 ✨