Updating

import { Aside } from ‘@astrojs/starlight/components’;

CompassDocs migrates its own database schema on start, so updating is almost always just “get the new code/image and restart.” Your data is preserved.

1.0 removes three database tables that have been unused since 0.99 (`space_groups`, `space_editors`, `space_editor_groups`). Their contents moved into role assignments automatically, and the upgrade copies anything still in them one last time before dropping them — so **no grant is lost by upgrading**, including on a jump straight from 0.98.

What you lose is the ability to go back. Rolling the app back below 0.99 after starting 1.0 leaves per-space grants with nowhere to live, so private-space membership and per-space edit rights would be gone. Take a database backup before you upgrade.

Want to check the migration before committing? Run tools/verify-rbac-migration.sql while still on 0.99 — it compares every migrated grant against the original row, which is only possible while those rows still exist:

psql "$DATABASE_URL" -f tools/verify-rbac-migration.sql

Every check should read OK. The script still works after upgrading; it just reports the three per-space checks as n/a once there is nothing left to compare against.

From **0.59.0** the container runs as a **non-root user** (uid/gid `1001`) as a security hardening. Data written by older (root) versions — attachments, backups, and any custom-TLS cert dir — is owned by root, so the new non-root process can't write to it until you hand ownership over **once**:

# From your install folder (the one with docker-compose.yml):
docker compose stop app
docker compose run --rm --no-deps --user 0 app chown -R 1001:1001 /uploads /backups
docker compose pull && docker compose up -d

This runs the chown through Compose itself, so it operates on the app service’s real volumes. (Avoid docker run -v <name>:... for this: Compose prefixes volume names with the project name — a default install’s uploads volume is actually compassdocs_compassdocs_uploads — and a mistyped name silently creates a fresh empty volume instead of fixing the real one.)

Bind-mounting host directories instead? Run sudo chown -R 1001:1001 /path/to/uploads /path/to/backups on the host. Fresh installs need nothing — new volumes get the right ownership automatically.

Don’t skip this even if uploads and backups look fine. The auto-generated master key file lives at /uploads/.secret.key, so when the uploads volume is still root-owned the non-root process can’t read it — and saving any encrypted credential fails (the SSO client secret, SMTP password, off-site backup credentials, and the Anthropic API key all report a generic “cannot be saved” in Settings). If you’re seeing that error after upgrading, this chown is the fix. Installs that set COMPASSDOCS_SECRET_KEY as an environment variable use no key file and aren’t affected by this particular symptom, but still need the chown for uploads and backups.

Check for updates in the app

Admins can see the current version and whether a newer release is available under Settings → System → Version & updates. When you’re behind, it links to the release notes and shows the exact upgrade command below — and if you deploy the optional updater companion (next section), an Update now button applies it right from the console.

One-click updates from the admin console (0.75.0)

A container can’t replace its own image, and CompassDocs deliberately never touches the Docker socket — a compromised web app must not mean a compromised host. Instead, a tiny updater companion holds the socket, listens only on the internal compose network, and does exactly one thing when the app pokes it: pull the newer image and recreate the app container.

Add this to your docker-compose.yml (and pick a long random token):

services:
  app:
    # ... your existing app service ...
    labels:
      - com.centurylinklabs.watchtower.enable=true
    environment:
      # ... existing vars ...
      COMPASSDOCS_UPDATER_URL: http://updater:8080
      COMPASSDOCS_UPDATER_TOKEN: ${UPDATER_TOKEN}

  updater:
    image: containrrr/watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --http-api-update --label-enable --cleanup
    environment:
      WATCHTOWER_HTTP_API_TOKEN: ${UPDATER_TOKEN}
    # No ports published — only the app can reach it, over the compose network.

Then docker compose up -d once, and Version & updates gains an Update to vX.Y.Z now button whenever a release is out: it triggers the updater (admin-only, written to the audit log), the app restarts on the new image, and the console confirms the new version — usually in under a minute.

Notes:

• The button follows whatever tag your app service runs. Use ghcr.io/mattny20/compassdocs:latest (releases also tag :latest as of 0.75.0) to follow all releases, or a :0.75-style tag to stay on a minor line. A fully pinned :0.75.0 never updates.
• The updater only recreates containers carrying the label — nothing else on the host is touched, and --cleanup removes the old image afterwards.
• No updater deployed? The panel simply keeps showing the manual command.

Docker

From your install folder (the one with docker-compose.yml):

docker compose pull && docker compose up -d

This pulls the latest image and recreates the app container. Your data lives in a Docker volume and is untouched. Re-running the install script does the same thing.

To move between specific versions, set COMPASSDOCS_VERSION in your .env and run the same two commands.

Manual (Node + Postgres)

From a release tarball (no git required)

Every release includes a source tar.gz. The Version & updates panel in the app shows these exact steps with the right version filled in, plus a direct download link.

# 1. Download and extract the release (replace X.Y.Z)
curl -fsSL https://github.com/mattny20/CompassDocs/archive/refs/tags/vX.Y.Z.tar.gz | tar -xz
cd CompassDocs-X.Y.Z

# 2. Bring over your configuration
cp /path/to/your/current/.env .

# 3. Build
npm ci && npm run build

# 4. Stop the old server, then start the new build
npm run start

Once the new version is up, the old directory can be deleted — your data lives in PostgreSQL, not the app directory.

From a git clone

# 1. Stop the running server (Ctrl+C)

# 2. Get the latest code
git checkout main
git pull origin main

# 3. Install dependencies
npm install

# 4. Start again
npm run dev      # or: npm run build && npm run start

No manual migrations

Schema changes are applied automatically on startup and are idempotent (guarded by a Postgres advisory lock), and new settings fall back to sensible defaults — so existing content and users carry over untouched.

You may be asked to sign in again

Session handling can change between versions, so an existing cookie might not carry over cleanly. Just log back in with your account.

Version notes

• 0.49 switches the bundled compose files from postgres:16 to pgvector/pgvector:pg16 to enable semantic search. It’s a drop-in superset of the same PostgreSQL major version — pull the new compose file (or edit the image line) and your existing data volume upgrades in place. Installs using an external PostgreSQL install the pgvector extension instead; without it, everything else works and semantic search reports itself unavailable.

Rolling back

With Docker, pin the previous version via COMPASSDOCS_VERSION and docker compose up -d. Migrations are additive, so rolling the app back is generally safe — take a database backup before any upgrade you’re unsure about.

One exception: 1.0 drops the three legacy per-space grant tables, so going back below 0.99 after starting 1.0 loses private-space membership and per-space edit rights. That is the one upgrade where the backup isn’t optional.