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 workingsudoprivileges. - A domain such as
YOUR_DOMAINwith an A record pointing toSERVER_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:3000in the Compose port mapping and do not publish PostgreSQL or Redis ports. - 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; 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
.envreadable 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.