Administration

Deployment shapes

Docleus has two supported Docker layouts.

Small

• One Docleus container.
• SQLite database.
• Local files in the docleus-data volume.
• One process handles HTTP and background jobs.

This is the simplest option for a small team and the recommended starting point. The database, blobs, configuration, backups, and runtime-installed plugins all live under /data.

Standard

• Docleus with PostgreSQL.
• S3-compatible blob storage.
• Separate Postgres and object-store services in the example compose file.
• Optional web and worker roles for separating HTTP from background jobs.

The compose file's bundled S3 server is a placeholder. Replace it with a supported S3-compatible service before relying on the standard layout in production.

Configuration sources

The container reads secrets from environment variables on every boot. It writes non-secret environment overrides into /data/docleus.yaml.

An environment variable that is set wins over the stored value. An unset or empty variable leaves the stored value alone. Settings edited directly in docleus.yaml are preserved unless the same value is supplied through the environment.

Common settings:

Keep secrets in the environment or a deployment secret manager. Do not commit an .env file or a populated /data/docleus.yaml.

Persistent data

In the small deployment, back up the entire /data directory. Important contents include:

The named volume survives container recreation. It does not protect against a host failure, accidental deletion, or corruption, so copy it to separate storage regularly.

Database choice

SQLite

• Recommended for a single instance with modest write concurrency.
• Requires no separate database service.
• Is automatically copied to /data/backups before migrations caused by a platform version or plugin-version change.

PostgreSQL

• Recommended when the instance needs higher concurrency or an existing managed database service.
• Migrations and access work through the same schema definitions as SQLite.
• Docleus does not create automatic PostgreSQL backups. Use pg_dump and restore testing as part of regular operations.

Do not switch the backing database by copying only one storage component. Database content, blob storage, and blob URL configuration must remain consistent.

Blob storage

Local blob storage is part of /data in the small deployment. The S3 plugin replaces the core blob provider when enabled and configured.

For an external S3-compatible store:

• Create the bucket before starting Docleus.
• Set a dedicated access key and secret.
• Use TLS for the endpoint whenever it crosses a network boundary.
• Set a stable signing secret of at least 32 characters.
• Include both the database and bucket in backup and restore plans.

Published sites keep their artifacts in blob storage. Removing a site does not immediately delete every artifact; the platform's daily unreferenced-blob collection reclaims them later.

Reverse proxy and TLS

Terminate TLS in front of Docleus. The proxy must forward:

• The original Host header.
• X-Forwarded-Proto.
• X-Forwarded-Host.
• X-Forwarded-For.

Set:

DOCLEUS_PUBLIC_URL=https://admin.example.com
DOCLEUS_TRUST_PROXY=true

Use HTTPS for both the editor and published sites. Secure session cookies and cross-site write checks depend on the public origin being correct.

The repository includes Caddyfile.example. A typical deployment uses:

• admin.example.com for the editor and API.
• www.example.com as a redirect to the public site.
• example.com for the published documentation site.

All hostnames that reach Docleus can be served by the same container; Docleus selects a site by hostname.

Network exposure

Expose only the reverse proxy's ports 80 and 443 to the internet. Keep the Docleus container port private when the proxy runs on the same Docker network. Do not expose PostgreSQL, SMTP credentials, or the object store directly.

Email

Configure SMTP to send invitation email automatically. If SMTP is not configured, invitations still work, but an administrator must copy and send the invitation link manually.

Use a dedicated sender and verify the provider's SPF, DKIM, and DMARC setup.

Plugin administration

Instance administrators install and remove plugins. Organization and space admins only choose which installed plugins are enabled in their scope.

Treat plugin installation as a privileged production change. Review the source, pin a version, test the upgrade, and back up data before replacing the image or installing a new plugin.