Connected apps with 3rd-party data hosts jsr.io/@civility
README.md

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, ...)
Email 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 the Dockerfile, 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 #


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)