Self-Hosting with Docker

Docker is the recommended way to run CompassDocs. Images are published to the GitHub Container Registry (ghcr.io/mattny20/compassdocs) automatically on every release.

Supported platforms

CPU architectures — the image is multi-arch, published for both, and Docker pulls the right one for your host automatically:

Architecture	Runs on
x86-64 (amd64)	Intel / AMD servers, desktops, and most cloud VMs
ARM64 (aarch64)	Apple Silicon (M-series), AWS Graviton, Ampere, Raspberry Pi 4/5 (64-bit OS)

Host operating system

• Linux — recommended for production. Any distribution with Docker Engine (Ubuntu, Debian, Rocky/RHEL, Fedora, …).
• macOS & Windows — via Docker Desktop. Great for evaluation and running locally.

Without Docker, CompassDocs is just a Next.js server plus PostgreSQL, so it also runs directly on any OS with Node.js 20+ and PostgreSQL 14+ — see Manual install.

Option A — the one-command installer

From a machine with Docker installed:

curl -fsSL https://raw.githubusercontent.com/mattny20/CompassDocs/main/install.sh | bash

This drops a docker-compose.yml and a .env (with generated secrets) into a ./compassdocs folder, starts the stack, and prints your admin login. Re-running it updates to the latest image without touching your data.

The installer takes two optional switches, combinable:

Switch	Effect
COMPASSDOCS_TLS=1	Bundles a Caddy reverse proxy (ports 80/443) so you can set your domain + HTTPS mode right in the setup wizard — automatic Let’s Encrypt or self-signed.
COMPASSDOCS_EDITION=enterprise	Installs the Enterprise edition instead.

curl -fsSL https://raw.githubusercontent.com/mattny20/CompassDocs/main/install.sh | COMPASSDOCS_TLS=1 bash

Option B — compose by hand

Grab deploy/docker-compose.yml and deploy/.env.example, put them in a folder, fill in the .env, and run:

docker compose up -d

A minimal .env:

# Database password (any strong random string)
POSTGRES_PASSWORD=change-me-to-a-long-random-string

# Initial admin account created on first launch
COMPASSDOCS_ADMIN_USER=admin
COMPASSDOCS_ADMIN_PASSWORD=change-me-to-a-strong-password

# Optional: enable AI answers (search works without it)
# ANTHROPIC_API_KEY=sk-ant-...

# Port to expose the app on (http://localhost:PORT)
PORT=3000

The app and database talk over a private Docker network, so TLS to the database is off by default (DATABASE_SSL=disable in the compose file). See Environment variables for the full list.

Ports & firewall

One inbound port serves everything. The web UI and the REST API (/api/*) are the same Next.js server — there is no separate API port.

Port	Used by	Exposed on the host?
3000 (host side; container always 3000)	App — web UI + API	Yes on a standard install. Change it with PORT in .env (e.g. PORT=8080 → http://host:8080).
80 / 443	Caddy reverse proxy — HTTP + HTTPS	Yes on a TLS install (COMPASSDOCS_TLS=1). The app itself is then not published on the host; all traffic goes through Caddy.
5432	PostgreSQL	No — private Docker network only, never reachable from outside.
2019	Caddy admin API (the app configures the proxy through it)	No — private Docker network only.

Firewall examples (Ubuntu ufw):

# Standard install (plain HTTP on port 3000)
sudo ufw allow 3000/tcp

# TLS install (Caddy on 80/443 — don't open 3000)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Outbound connections the app may make — all ordinary HTTPS (443), nothing to open inbound:

• api.anthropic.com — AI answers & proofreading (only if an API key is set)
• api.github.com — the update check in Settings → System
• Let’s Encrypt (by Caddy, TLS installs) — certificate issuance/renewal; the ACME challenge also requires inbound 80/443 to be reachable
• Your S3/Azure endpoints — only if off-site backups are configured

Port already in use?

If something else runs on 3000, set PORT=<free port> in .env and docker compose up -d. Only the host-side mapping changes — inside the container the app always listens on 3000.

Data & volumes

The compose stack creates named volumes that persist across restarts and image updates:

• compassdocs_pgdata — the PostgreSQL database
• compassdocs_backups — database backup files (/backups)
• compassdocs_uploads — document attachments (/uploads)

Those are the names as declared in the compose file. Docker prefixes them with the Compose project name (your install folder’s name) at runtime — on a default install docker volume ls shows e.g. compassdocs_compassdocs_uploads. For one-off maintenance on a volume, prefer docker compose run --rm --no-deps <service> … (which mounts the service’s real volumes) over docker run -v <name>:…, where a mistyped name silently creates a new empty volume.

For backups, use the built-in scheduler and one-click restore in Settings → Backups — see Backups & restore.

Custom domain & HTTPS

To serve CompassDocs on your own domain with automatic TLS, use the included Caddy stack instead — see Custom domain & HTTPS.

Updating

From your install folder:

docker compose pull && docker compose up -d

The app migrates its own schema on start, so there are no manual upgrade steps. See Updating for details.

Pin a specific version

By default you get the latest image. To pin a release, set COMPASSDOCS_VERSION in your .env:

COMPASSDOCS_VERSION=1.0.0