Hosting Civility #
Everything you need to run a self-hosted Civility sync server — the backend that stores and syncs data for Civility apps.
A Civility server has three concerns, each with a built-in default and an upgrade path:
| Concern | Default (zero-setup) | Upgrade |
|---|---|---|
| Database | SQLite | PostgreSQL |
| Blobs | Local filesystem | S3-compatible (R2, AWS, ...) |
| Console (logs) | Resend or SMTP |
The server is the same in every case; you pick adapters via environment variables. Start local with the quickstart, pick a deployment template when you're ready to ship, and turn on features as you need them.
Every running server serves its own API reference: Swagger UI at /api/v1, OpenAPI JSON at /api/v1/doc, both generated from the route schemas.
Quickstart #
Install the civ CLI, run civ api start, answer a few prompts. Good for local development, a single-VPS deployment, or trying things out.
1. Prerequisites #
# Install Deno 2.9+ (the default SQLite adapter uses node:sqlite,
# the SQLite engine built into the Deno binary — no native library needed)
curl -fsSL https://deno.land/install.sh | sh
# Install the Civility CLI
deno install jsr:@civility/cli -Afg --name=civ
2. First run — interactive setup #
Run civ api start with no arguments. The CLI walks through setup and saves your answers to ~/.config/civility/api.json:
civ api start
ℹ Civility API server setup
? Data storage
❯ SQLite (local file, no setup required)
PostgreSQL (requires DATABASE_URL)
? File/blob storage
❯ Local filesystem (simple, no external services)
S3-compatible (requires S3_ENDPOINT, S3_BUCKET, ...)
? Port [8080]
? Hostname [0.0.0.0]
? Use a custom database path? [no]
? Blob storage directory [./.data/blobs]
ℹ Admin panel: set CIVILITY_ADMIN_EMAILS and/or CIVILITY_ADMIN_TOKEN to enable
✓ Config saved to ~/.config/civility/api.json
ℹ Starting Civility server on port 8080
ℹ Adapters: fs/sqlite
ℹ API docs: http://localhost:8080/api/v1
ℹ Dashboard: http://localhost:8080/dashboard
⚠ Admin panel disabled — set CIVILITY_ADMIN_EMAILS and/or CIVILITY_ADMIN_TOKEN to enable
Subsequent runs start immediately using the saved config. Re-run the wizard (previous answers become defaults) with civ api start --reset.
3. Choosing adapters #
Data storage:
| Adapter | When to use |
|---|---|
| SQLite (default) | Single-server, no ops burden. A local SQLite file on disk (or :memory:). |
| PostgreSQL | Multiple server instances, existing PG infrastructure, or managed DB (Neon, Supabase, Railway). |
File/blob storage:
| Adapter | When to use |
|---|---|
| Local filesystem (default) | Single-server with local disk. Blobs served directly by the Civility server at /blobs/*. |
| S3-compatible | Off-server blob durability (AWS S3, Cloudflare R2, Hetzner Object Storage, MinIO). |
The adapters you pick here are passed as environment variables; the full S3 provider endpoint reference (R2, Hetzner, MinIO, Backblaze, ...) lives in the manual guide appendix.
4. Non-interactive usage #
Any CLI flag skips the wizard entirely and leaves the config file untouched — use this for containers, CI, or scripted restarts.
civ api start --port 9000 # override just the port
civ api start --db pg --blobs s3 # Postgres + S3, overriding saved choices
civ api start \
--port 8080 --hostname 127.0.0.1 \
--db sqlite --blobs fs \
--db-path /var/lib/civility/civility.db \
--blob-path /var/lib/civility/blobs \
--max-db-bytes 104857600 --max-blob-bytes 1073741824
5. Stored config #
The config file at ~/.config/civility/api.json contains only non-secret values — secrets are always passed as environment variables, never written to disk:
{
"port": 8080,
"hostname": "0.0.0.0",
"db": "sqlite",
"blobs": "fs",
"blobPath": "./.data/blobs"
}
Edit by hand or re-run civ api start --reset to update it through the wizard.
Deploying #
Every template runs the same @civility/hono server; they differ only in where state lives and how the host wraps the container.
Pick a template #
| Template | State | Best for | Scaling |
|---|---|---|---|
| docker/sqlite | SQLite + filesystem, one volume | Simplest self-host — one container, nothing external to provision. | Single instance |
| docker/sqlite-s3 | SQLite on a small volume + S3 blobs | Single container, but blobs on cheap object storage / behind a CDN. | Single instance |
| manual VPS | SQLite/Postgres + filesystem/S3 | A single Linux VPS with civ api start under systemd + Caddy. |
Single by default |
Not sure? Start with docker/sqlite. Move to docker/sqlite-s3 when blobs outgrow the local disk, and to docker/postgres when you need managed backups, multiple replicas, or a PaaS that provisions databases as separate resources.
All Docker templates share the same env-driven main.ts; only the adapter set and the wrapper files (Dockerfile, docker-compose*.yml) differ.
Optional files #
Delete the ones your host doesn't need:
fly.toml— Fly.io only; Fly builds from theDockerfile, this just adds machine/volume config.docker-compose.local.yml(docker/postgres,docker/sqlite-s3) — a local dev stack (Postgres + MinIO, or just MinIO). Not for production.
Coolify and most container PaaSes work from the Dockerfile or docker-compose.yml directly; set environment variables in their dashboard.
Environment variables #
Secrets and adapter selection are always passed as environment variables (never written to disk by the server):
| Variable | Purpose |
|---|---|
PORT |
Bind port (default 8080). The server binds 0.0.0.0:$PORT. |
CIVILITY_DB_PATH |
SQLite database file path (default ./.data/civility.db). |
S3_ENDPOINT + S3_* |
S3-compatible blob storage (S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY, S3_REGION, S3_CDN_URL_BASE). Absent → local filesystem. |
CIVILITY_AUTH_SECRET |
JWT signing key. Generate once (openssl rand -hex 32) and keep stable. |
CIVILITY_ADMIN_TOKEN |
Bearer token for the /admin JSON API (scripts). Generate with openssl rand -hex 32. |
CIVILITY_ADMIN_EMAILS |
Comma-separated account emails granted /admin access via their normal dashboard sign-in. |
OTEL_DENO + OTEL_* |
OpenTelemetry traces/metrics/logs. |
Pass them inline for local testing (CIVILITY_ADMIN_EMAILS=you@example.org civ api start); for long-running deployments use systemd's EnvironmentFile, a process manager, or your PaaS dashboard. Each template documents its own subset in a .env.example.
Adding features #
- Admin panel — configure SMTP/Resend email, manage users and grants (
CIVILITY_ADMIN_EMAILS/CIVILITY_ADMIN_TOKEN). - Account security & MFA — what operators can and can't control.
- CivServices / AI — bundle credentials and the outbound proxy.
- Observability — OpenTelemetry traces, metrics, logs.
- Operations — log rotation, capacity planning, when to scale.
- Billing & subscription tiers — Stripe integration (hosted service only).
Operating it #
- Runbook — deploy, verify, roll back, back up, respond to incidents.
Map of this directory #
hosting/
├── README.md ← you are here (overview + quickstart + deployments)
├── manual_deployment.md ← VPS via systemd + Caddy (+ S3 provider appendix)
├── runbook.md ← hosted-service ops: deploy, rollback, backups, on-call
├── docker/
│ ├── sqlite/ ← single-resource (sqlite + fs volume)
│ ├── sqlite-s3/ ← single container, sqlite + s3 blobs
│ └── postgres/ ← multi-resource (postgres + s3)
└── features/
├── admin.md ← /admin panel (email config, users, grants)
├── auth.md ← authentication & MFA
├── services.md ← CivServices: bundle credentials, proxy, overrides
├── observability.md ← OpenTelemetry
├── operations.md ← log rotation, capacity planning
└── billing.md ← Stripe billing / subscription tiers (hosted only)