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.

• 1.17.0 adds two tables (link_clicks and user_quick_links) and three columns (links.dashboard_featured, links.signin and users.dashboard_hidden) for the new dashboard and quick links, applied on start like every schema change. There is no new environment variable. Rolling back to 1.16.0 is safe: it ignores the new tables and columns.

• 1.18.0 adds five tables (handbooks, handbook_sections, handbook_items, handbook_audience and handbook_confirmations) and three columns (documents.find_mode, documents.summary_points and documents.applies_to) for policy handbooks, applied on start like every schema change. There is no new environment variable. The Administrator role gains Build handbooks (handbook.manage); custom roles don’t, so add it to a role, or grant it on a space, to let others build handbooks. Rolling back to 1.17.0 is safe: it ignores the new tables and columns. While you are on 1.17.0, handbook-only documents show in their spaces again, handbooks and the access they give go away until you upgrade again, and, with read confirmation, the hourly audience sweep closes the confirmation requests of people who were asked only through a handbook. Their confirmations are kept.

• 1.19.0 adds the helpdesk (Enterprise, helpdesk), email templates built from parts and notification policies. The schema is additive and applied on start: 37 hd_* tables, email_template_parts and email_template_compositions, and user_notify_prefs, notify_digest_queue and notify_digest_state. No existing table changes. Four optional environment variables are new (COMPASSDOCS_PUSH_SUBJECT, COMPASSDOCS_PUSH_HOSTS and COMPASSDOCS_HD_ATTACHMENT_MAX_MB, see Helpdesk; and DATABASE_POOL_WAIT_MS, see Database, which limits how long a request waits for a free database connection to 30 seconds by default, where before it waited forever), and push needs outbound access to the browsers’ push services. Every built-in role gains Get help and the Administrator role the other helpdesk and notification policy permissions; custom roles gain nothing. A custom role already named “Helpdesk agent” or “Helpdesk manager” keeps its people and permissions, and its key moves to helpdesk-agent-custom (or helpdesk-manager-custom) to make room for the new built-in role. Inbound helpdesk mail is linked to an account only when your mail provider reports passing sender results. Every email gains the Standard header and footer unless an admin chose otherwise. Every minute, each instance runs the helpdesk’s sweeps (they do nothing without the license), and the hourly tick sends the new email digests. Rolling back to 1.18.4 is safe: it ignores the new tables, and personal notification choices are also kept where 1.18 reads them. Emails go back to 1.18’s layout and to the template wording saved before the upgrade, which 1.19.0 reads but never changes; edits made in 1.19.0 come back when you upgrade again. See Upgrading to 1.19.0.

• 1.19.1 adds to the helpdesk: merging and bulk edits, CCs and followers, presence and collision warnings, saved views, business-time counting in workflows, shortcut defaults, retention and legal hold, a customer portal at /support, import from Zoho Desk or CSV, recurring tickets, time tracking, and helpdesk tools in the Claude connector. The schema is additive and applied on start: 13 new hd_* tables and new columns on hd_tickets, hd_messages and hd_teams. There is no new environment variable. What changes on upgrade:

  • New behaviour is off. Closing solved tickets automatically, the anonymise-or-delete retention period and the customer portal are all off until an admin turns them on, so nothing is closed, anonymised or deleted by upgrading. Removing an account now anonymises that person’s helpdesk tickets (except tickets on legal hold); an admin can turn that off in Desk settings → Retention and privacy. Workflow waits, due dates and reminders keep counting calendar time.
  • Admins’ replies are sent. 1.19.0 held every desk Admin’s public reply for review by mistake. 1.19.1 fixes it; replies still held from 1.19.0 wait under Reviews for a lead to approve.
  • License. Every valid Enterprise license includes the helpdesk, including keys issued before 1.19; you no longer need a key that lists helpdesk. The enterprise image is still required.
  • Desk roles. Merge tickets and Bulk edit are back, on for Agent and above. A role customised in 1.19.0 gets Merge only if it can change status, and Bulk edit only if it can change a field.
  • Portal domain. If you turn the portal on, set your domain under Settings → Domain & HTTPS first, so sign-in links always point to it.

  Rolling back to 1.19.0 is safe: it ignores the new tables and columns (tickets already anonymised or deleted stay that way). See Upgrading to 1.19.1.

• 1.19.2 adds to the helpdesk: major incidents, status services for teams, skills and languages in assignment, checklists and canned responses, a satisfaction survey in the customer portal, reply-all threading and the import’s dry run in the background. The schema is additive and applied on start: 20 new hd_* tables (canned responses and their uses; skills, languages and agents’ tags; checklist templates and ticket checklists with their items; major incidents, their links, updates and the people affected; team status services, spells of trouble and who was told or asked; and the desk’s “New” badges), two new columns on hd_tickets (language and language_source) and four on hd_import_jobs (check_kind, check_progress, check_by and check_error). No existing data changes. There is no new environment variable. What changes on upgrade:

  • Nothing destructive happens. Nothing is linked, assigned, solved or deleted by upgrading. Skills, checklists, canned responses and team status services start empty, and no team follows a Status page service until someone chooses. Tickets raised from now on get a language; existing tickets stay Unknown until an agent sets one.
  • Desk roles. Two new capabilities: Link tickets to a major incident (Agent and up) and Run major incidents (Team lead and up). A role customised before gets Link only if it can change status, and Run only if it can also reply to requesters. The macro capabilities also cover canned responses.
  • New notifications: Major incident updates (requesters, bell and email), A service your team uses is down (agents, bell and push) and Import checks (bell). See Notification policies.
  • The import API changed. POST /api/helpdesk/admin/import/<id>/dry-run now answers 202 at once and runs in the background; poll GET /api/helpdesk/admin/import/<id> until the status is ready. A script that read the dry run’s counts from its answer must poll instead. See The import API.

  Rolling back to 1.19.1 is safe: it ignores the new tables and columns. See Upgrading to 1.19.2.

• 1.19.3 adds assets from Snipe-IT to the helpdesk: an Assets card on each ticket, an asset’s page with its tickets and maintenance, logging a maintenance record in Snipe-IT when a ticket is solved, a Device field in Get help, and hd_asset_lookup in the Claude connector. The schema is additive and applied on start: three new tables (hd_assets, hd_ticket_assets and hd_asset_maintenance_log). No existing data changes. There is no new environment variable. What changes on upgrade:

  • Nothing reaches Snipe-IT until an admin connects it in Desk settings → Assets. The sync runs every 30 minutes with the other helpdesk sweeps, only with the helpdesk licensed and Snipe-IT connected.
  • A Snipe-IT server on a private network needs COMPASSDOCS_FETCH_ALLOW_PRIVATE=1, like other outbound connections. Loopback addresses are always refused. See A Snipe-IT server on a private network.
  • Desk roles gain no capability: connecting needs Helpdesk settings, linking needs only to work the ticket, and logging maintenance needs Change status.

  Rolling back to 1.19.2 is safe: it ignores the new tables. See Upgrading to 1.19.3.

• 1.19.4 adds to the helpdesk: chat apps (raise, follow and approve requests from Microsoft Teams or Slack, and open tickets from channels), API tokens, a REST API under /api/helpdesk/v1 and signed outgoing webhooks, a help centre in the customer portal, Microsoft Intune as an asset source, artwork behind the desk, sharing and printing tickets and a recycle bin for deleted tickets. The schema is additive and applied on start: 11 new tables and six new columns (hd_tickets.deleted_at, deleted_by, deleted_by_name, hd_messages.event, hd_assets.assigned_upn, hd_portal_links.hc_journey). No existing data changes. There is no new environment variable. What changes on upgrade:

  • Deleting a ticket moves it to the recycle bin, restorable for 30 days, and a daily sweep deletes it for good after that. Retention’s Delete does the same.
  • Desk roles: Delete tickets now moves tickets to the bin. Delete for good is new and only Admin holds it by default, so anyone else who could delete for good before now moves tickets to the bin. Customised roles keep Delete tickets and never gain Delete for good.
  • Nothing reaches Microsoft Teams, Slack, Intune or a webhook receiver until an admin sets it up. The help centre is off and the desk has no artwork until someone turns them on, and agents can’t choose their own desk background until an admin allows it.
  • Intune needs the DeviceManagementManagedDevices.Read.All application permission on the Microsoft 365 directory sync’s app registration.
  • A webhook receiver on a private network needs COMPASSDOCS_FETCH_ALLOW_PRIVATE=1. Loopback addresses are always refused.

  Before rolling back to 1.19.3, restore or delete for good the tickets in the recycle bin: 1.19.3 doesn’t know the bin, so it shows them as ordinary tickets and never purges them. It otherwise ignores the new tables and columns. See Upgrading to 1.19.4.

• 1.20.0 adds Claude in the desk to the helpdesk: a Claude chat docked beside the open ticket that works as the agent, drafts into the reply box and suggests changes the agent applies, using the workspace’s Anthropic API key. The schema is additive and applied on start: five new tables (hd_claude_chats, hd_claude_chat_tickets, hd_claude_messages, hd_claude_cards, hd_claude_usage) and a new setting (hd_claude_desk). No existing data changes. There is no new environment variable to set. What changes on upgrade:

  • Nothing is on until an admin turns it on. Claude in the desk is off by default, and so is its web search. Once it is switched on, every team has it and there is no monthly spending limit until you set one.
  • It needs the Anthropic provider and API key in Settings → AI, and the helpdesk licence. It is billed per use to that key.
  • Settings → AI’s models are now Claude Opus 5.5 (the default), Claude Sonnet 5.5 and Claude Haiku 5.5. A model you saved before is kept. Without a saved model, the default moves to claude-opus-5-5 (or whatever COMPASSDOCS_AI_MODEL says).
  • Proofreading, writing help and Ask say plainly when Claude declines.
  • The Anthropic SDK (@anthropic-ai/sdk) moves from 0.68 to 1.6.0, now under the Apache-2.0 licence (it was MIT). If you build from source, the usual npm ci or npm install step installs it.
  • A new helpdesk sweep deletes Claude chats that have no ticket after 90 idle days.
  • COMPASSDOCS_ANTHROPIC_BASE_URL exists for the test suite only. Don’t set it in production.

  Rolling back to 1.19.4 is safe: it ignores the new tables and setting. If you saved one of the new models in Settings → AI, pick one of 1.19.4’s models after rolling back. See Upgrading to 1.20.0.

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.