Skip to content

Operations

Before going live

Complete these checks before exposing a new instance:

  • Use a production hostname and a valid TLS certificate.
  • Set DOCLEUS_PUBLIC_URL and, behind a reverse proxy, DOCLEUS_TRUST_PROXY=true.
  • Store secrets outside the repository.
  • Create a backup schedule for the database, blobs, and configuration.
  • Test a restore, not only a backup.
  • Restrict instance administrator access.
  • Install only reviewed plugins with pinned versions.
  • Publish and inspect a test site on desktop and mobile.

Backups

Small deployment

Back up the complete docleus-data volume while Docleus is stopped so the SQLite database and files are consistent:

docker compose -f compose.small.yaml stop docleus
mkdir -p backups
docker compose -f compose.small.yaml cp docleus:/data/. backups/docleus-data
docker compose -f compose.small.yaml start docleus

Store the copied directory off the host and encrypt backups if they contain private content or secrets. Keep multiple recovery points.

To restore:

docker compose -f compose.small.yaml stop docleus
docker compose -f compose.small.yaml cp backups/docleus-data/. docleus:/data
docker compose -f compose.small.yaml start docleus

Restore only into a matching or compatible image version. If the source and target platform versions differ, test migrations in a separate environment first.

PostgreSQL deployment

Back up both components:

  • The PostgreSQL database with pg_dump.
  • The configured blob store or S3 bucket.
  • /data/docleus.yaml, installed plugins, and any other persistent Docleus settings.

Keep database and blob backups from the same approximate point in time. A database restored without its corresponding blobs can contain broken uploads and publications.

Upgrades

Every release pins the core and default plugins to versions tested together. Check COMPATIBILITY.md before replacing an image.

  1. Read the release notes and compatibility file.
  2. Back up the database, blobs, and configuration.
  3. Pull or build the new image.
  4. Recreate the container with docker compose ... up -d.
  5. Wait for migrations to finish and inspect the logs.
  6. Verify sign-in, a page, a publication, search, and llms.txt.

Migrations run at boot. To run them without serving, start a one-off container with the migrate argument:

docker compose -f compose.small.yaml run --rm docleus migrate

If a migration or plugin compatibility check fails, stop the new container, restore the pre-upgrade backup, and start the previous image. Do not keep retrying against a partially migrated database.

Publication rollback

Content rollback and deployment rollback are different operations:

  • Publication rollback: activates an earlier immutable site publication without changing main. Use Space settings > Site > Roll back.
  • Deployment rollback: restores the previous image and, when required, a compatible database and blob backup.

Use publication rollback for content mistakes. Use deployment rollback for a bad platform or plugin upgrade.

Static export

The CLI can export a publication to a directory:

pnpm docleus export \
  --site <org-slug>/<site-slug> \
  --out <directory> \
  --data <data-directory>

By default it exports the active publication. Add --publication <id> to export a specific one. The output directory must be empty.

A static export does not include server-side features such as site search that depend on the live instance. Check every interactive block and navigation path on the target host.

Health checks

At minimum, monitor:

  • https://<editor-host>/api/auth/methods for a successful response.
  • The public site root and a deep page.
  • The publication timestamp after planned releases.
  • Container restart count and disk usage.
  • Database availability and backup completion.

For a functional check, sign in and open a page after each upgrade. For a published-site check, fetch the site root and confirm it contains expected content rather than only checking for a 200 status.

Troubleshooting

The setup page says setup is already complete

The instance has an administrator. Sign in instead of rerunning setup. If the administrator credentials are lost, restore access through a controlled administrative recovery process; do not delete the production database.

The setup token is missing

Read the first boot logs:

docker compose -f compose.small.yaml logs docleus

The token is printed only while the instance has no users.

Sign-in or writes fail behind a proxy

Check that the original host and protocol reach Docleus and that DOCLEUS_PUBLIC_URL uses the exact public HTTPS origin. Set DOCLEUS_TRUST_PROXY=true only when a trusted proxy supplies the forwarding headers.

The site shows old content

The change may not be merged into main, or the site may not have been published since the merge. Open Space settings > Site and compare the live publication with the current main revision.

A custom domain returns 404

Confirm that:

  • The DNS record points to the intended host.
  • The domain is set on the site.
  • The reverse proxy forwards the original Host.
  • The site has an active publication.

A plugin blocks startup

The log reports plugin/engines-mismatch when an installed plugin does not support the platform version. Upgrade or uninstall that plugin, or remove its row from /data/docleus.yaml before restarting.

Collaboration disconnects

Verify that the reverse proxy forwards WebSocket upgrades for /api/collab and that only one Docleus web process owns the instance unless a collaboration fan-out provider is configured. The in-process collaboration provider does not coordinate sessions across independent web processes.