Backups Updates and Monitoring

Backups, Updates and Monitoring

Your pages are in Git, but a full backup needs two things: the data volume and the database. Git alone restores the content, not accounts, access rights or the search index.

Backups

Where	What	Why
Data volume (/app/data)	Git repositories of the spaces, uploads, the generated secret	The content
PostgreSQL	Accounts, access rights, the search index, live-editing state	Everything around the content
Remote Git repository	Pages of spaces connected to a remote, after each sync	A second copy that needs no Folio

docker compose exec -T postgres pg_dump -U folio folio > folio-db.sql
docker compose exec -T app tar czf - -C /app/data . > folio-data.tgz

On the VPS install, cd /opt/folio && ./install.sh backup writes both files into backups/. Copy them off the server. The volume includes /app/data/.folio-secret (it encrypts saved Git tokens and AI keys); if you set FOLIO_SECRET yourself, keep it and never change it.

Restore onto a fresh installation (no accounts yet) is in INSTALL.md. Inside Folio: the trash restores deleted pages, page history restores any revision (a restore adds a commit), and Take the version from git saves the current state to a folio-backup/<timestamp> branch before resetting.

Updates

cd folio && git pull && docker compose up -d --build

Published-image installs: docker compose pull && docker compose up -d, or ./install.sh update on the VPS kit (it backs up first). Back up before every upgrade.

• Migrations run at start and move forward only. The project ships forward SQL migrations and no downgrade scripts, so going back means restoring the backup.
• The first start after some upgrades re-reads every document. The page index is rebuilt once; the server starts listening first, but a very large space can answer slowly for a few minutes, and tags, links and graph data are incomplete until the scan passes it.
• New settings are optional; an unset one keeps its default or leaves its feature off. Read the changelog for the version you jump to (0.4.0 adds migrations 045 to 047).

Monitoring

• Containers: docker compose ps and docker compose logs app --tail 100. The app has a health check on /api/health.
• After an install or upgrade: node deploy/smoke.mjs https://wiki.example.com signs up, makes a space and a page and tests real-time editing on a fresh instance.
• Sync state is visible per space (clean, ahead, behind, conflict, error); conflicts are listed for the whole space.
• Rate limits and caches live in one server process: a restart resets them.

Optional error reporting (Sentry), off by default

Set SENTRY_DSN to a Sentry project you own and Folio reports unhandled errors, 5xx answers and sampled traces, and the user menu gets Report a problem. Nothing goes to the Folio authors. Never sent: page content or titles, search words, text typed in forms and editors, request bodies, cookies, Authorization headers, query strings; no Session Replay. The user is the internal id only. With no DSN, no library loads and nothing connects. Enable "Prevent Storing of IP Addresses" in Sentry if you do not want a country derived from IPs.

Optional analytics hook (PostHog), off by default

For people running a public demo: set FOLIO_POSTHOG_KEY to a PostHog project of your own and Folio sends anonymous events (page kinds, space slugs, whether a search found anything, never content, titles, names or emails). Do Not Track turns it off. A default install sends no telemetry.

Limits

• Rate limit counters reset on restart; a second process counts on its own.
• Emptying the trash may leave a folder with nested pages inside the service trash folder (known defect).
• Serverless hosting and DigitalOcean App Platform (no persistent volumes) cannot run Folio.

See also

Install guides · INSTALL.md · Error reporting · FAQ and Troubleshooting