This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.
What Docmost does and what it needs
Docmost is an open-source collaborative wiki and documentation platform. It supports real-time editing, spaces, permissions, comments, page history, diagrams (Draw.io, Excalidraw, Mermaid), file attachments, and embeds. The stack is a NestJS backend, a React frontend, Postgres for data, and Redis for caching and real-time features.
The official Docker Compose file defines three services: docmost, db (Postgres 18), and redis (Redis 8). Docmost stores uploaded files in /app/data/storage, which must be persisted. The project does not publish a minimum RAM requirement. Memory usage scales with active users, page history, and attachment size; idle instances are lightweight, while heavy collaboration or large file uploads will need more.
Prerequisites, ports, and volume constraints
- A Linux server with Docker Engine 24+ and the Compose plugin.
- A domain name pointing to your server (for HTTPS).
- Port 3000 is the default Docmost HTTP port. You will bind it to localhost and put a reverse proxy in front.
- Three named volumes are required:
docmost(file storage),db_data(Postgres data), andredis_data(Redis AOF). - The official compose uses
postgres:18andredis:8. Keep these versions unless you have a reason to change them. -
APP_SECRETmust be at least 32 characters. Generate it withopenssl rand -hex 32. -
APP_URLmust be the public URL users will access, e.g.https://docs.example.com. It is used for links and redirects. -
DATABASE_URLandREDIS_URLare constructed from environment variables in the compose file below.
Production Docker Compose setup
Create a project directory and write the compose file and .env.
mkdir -p ~/docmost && cd ~/docmost
cat <<'EOF' > compose.yml
services:
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
PORT: ${PORT:-3000}
TZ: ${TZ:-UTC}
FILE_UPLOAD_SIZE_LIMIT: ${FILE_UPLOAD_SIZE_LIMIT:-50mb}
PAGE_HISTORY_INTERVAL: ${PAGE_HISTORY_INTERVAL:-5m}
DISABLE_TELEMETRY: ${DISABLE_TELEMETRY:-false}
IFRAME_EMBED_ALLOWED: ${IFRAME_EMBED_ALLOWED:-false}
IFRAME_ALLOWED_ORIGINS: ${IFRAME_ALLOWED_ORIGINS:-}
DEBUG_MODE: ${DEBUG_MODE:-false}
DEBUG_DB: ${DEBUG_DB:-false}
LOG_HTTP: ${LOG_HTTP:-false}
ports:
- "127.0.0.1:${PORT:-3000}:${PORT:-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:
EOF
Now create the .env file. Replace docs.example.com with your domain and set a strong database password.
cat <<'EOF' > .env
APP_URL=https://docs.example.com
PORT=3000
APP_SECRET=REPLACE_WITH_OPENSSL_RAND_HEX_32
DB_PASSWORD=REPLACE_WITH_STRONG_DB_PASSWORD
TZ=UTC
FILE_UPLOAD_SIZE_LIMIT=50mb
PAGE_HISTORY_INTERVAL=5m
DISABLE_TELEMETRY=false
IFRAME_EMBED_ALLOWED=false
IFRAME_ALLOWED_ORIGINS=
DEBUG_MODE=false
DEBUG_DB=false
LOG_HTTP=false
EOF
Generate the secrets and insert them into .env:
sed -i "s|REPLACE_WITH_OPENSSL_RAND_HEX_32|$(openssl rand -hex 32)|" .env
sed -i "s|REPLACE_WITH_STRONG_DB_PASSWORD|$(openssl rand -hex 16)|" .env
Start the stack:
docker compose up -d
Check logs for migration and startup messages:
docker compose logs -f docmost
Docmost will be available on http://127.0.0.1:3000 on the host. Do not expose port 3000 publicly; use a reverse proxy.
Reverse proxy, HTTPS, and first-run hardening
Docmost needs WebSocket support for real-time collaboration. Your reverse proxy must forward Upgrade and Connection headers. Also set X-Forwarded-Proto and X-Forwarded-For so Docmost generates correct URLs.
Example Caddy configuration (/etc/caddy/Caddyfile):
docs.example.com {
reverse_proxy 127.0.0.1:3000 {
header_up X-Forwarded-Proto {scheme}
header_up X-Forwarded-For {remote_host}
}
}
Caddy handles WebSocket upgrades automatically. For Nginx, add:
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
client_max_body_size 50m; # match FILE_UPLOAD_SIZE_LIMIT
}
After the proxy is up, visit https://docs.example.com. The first user to sign up becomes the workspace owner. Complete the setup immediately and disable open registration if you do not want others to create accounts. Docmost does not have a separate admin signup toggle in the environment variables; the first account is the admin. Use the UI to invite users or restrict access.
If you need to test without a domain, you can temporarily bind port 3000 to 0.0.0.0 in compose, or use an SSH tunnel: ssh -L 3000:127.0.0.1:3000 user@server. Remember to revert to localhost binding.
Updating, backups, and common pitfalls
To update Docmost and its dependencies:
docker compose pull
docker compose up -d
Always back up before updating. The critical data lives in the docmost volume (file storage) and the db_data volume (Postgres). Redis data is cache and can be rebuilt, but backing up redis_data is harmless.
Backup commands using a temporary container:
docker run --rm -v docmost_docmost:/data -v $(pwd):/backup alpine tar czf /backup/docmost_storage_$(date +%F).tar.gz -C /data .
docker run --rm -v docmost_db_data:/var/lib/postgresql -v $(pwd):/backup alpine tar czf /backup/docmost_db_$(date +%F).tar.gz -C /var/lib/postgresql .
For a consistent database dump, use pg_dump:
docker compose exec db pg_dump -U docmost docmost > docmost_db_$(date +%F).sql
Two operational pitfalls from the docs:
- Migrations run automatically on startup in the Docker image. If you skip a version or downgrade, the database schema may be incompatible. Always back up and test updates in a staging environment if possible.
-
File uploads and page history can grow storage. Monitor the
docmostvolume and adjustFILE_UPLOAD_SIZE_LIMITandPAGE_HISTORY_INTERVALas needed. The default history interval is 5 minutes; lowering it increases database writes.
Also ensure APP_URL matches the public URL exactly, including scheme. Mismatched URLs cause broken links and WebSocket failures.
Measured in our sandbox run: total memory 372.7 MB (sum of per-container peaks over a 30s idle window after startup) across 3 containers; largest container 301.8 MB; published port(s) 3000; HTTP probe returned 200. The run took 63.7s including the image download. Required secret(s) APP_SECRET, APP_URL, DB_PASSWORD were generated for the test run, as the tutorial instructs. Container breakdown: docmost 301.8 MB, db 56.2 MB, redis 14.6 MB.
Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.
Originally published with full interactive benchmark metrics and server sizing notes at https://vpsfolio.pages.dev/self-host-docmost-docker-compose/.
Top comments (0)