Civility on Docker — SQLite + filesystem (single-resource) #
The simplest production deployment: one container, one volume. The database (SQLite via @civility/hono/db/sqlite) and blobs (local filesystem) both live on a single mounted volume. No external Postgres, no S3, nothing else to provision.
Civility container (this template)
│
└─── /data volume
├── civility.db (SQLite database)
└── blobs/ (filesystem blob store)
For a single VPS, a home server, or one Fly machine. The trade-off is that it's single-instance only — no replicas against the same SQLite file. If blobs outgrow the disk, move them to a bucket with ../sqlite-s3/; for horizontal scaling or managed backups, use ../postgres/.
Files in this directory #
| File | Purpose |
|---|---|
main.ts |
Entry point: SQLite DB + filesystem blobs under DATA_DIR. |
Dockerfile |
Alpine-based build — SQLite ships inside the Deno binary. |
docker-compose.yml |
One service + one named volume. |
deno.json |
Pins @civility/hono. |
.env.example |
Environment variables, documented. |
fly.toml |
Optional, platform-specific: only needed to deploy to Fly.io. |
Quick start #
cp .env.example .env
echo "CIVILITY_AUTH_SECRET=$(openssl rand -hex 32)" >> .env
# Your operator account — sign up with this address to reach /admin.
echo "CIVILITY_ADMIN_EMAILS=you@example.org" >> .env
docker compose up -d --build
Then visit:
- Dashboard: http://localhost:8080/dashboard
- API docs: http://localhost:8080/api/v1
- Admin panel: http://localhost:8080/admin/ (sign in to the dashboard with an account listed in
CIVILITY_ADMIN_EMAILS)
Put a reverse proxy (Caddy, nginx, Traefik) in front for HTTPS — see the manual VPS guide for a Caddyfile example.
Run with plain Docker #
docker build -t civility-sqlite .
docker run -d --name civility -p 8080:8080 \
-v civility-data:/data \
-e CIVILITY_AUTH_SECRET='...' \
-e CIVILITY_ADMIN_EMAILS='you@example.org' \
--restart unless-stopped \
civility-sqlite
Everything durable is under /data, so the named volume civility-data is the whole of your state.
Deploy to Coolify #
- + New → Application, point it at the repo holding this directory, choose the Dockerfile (or Docker Compose) build pack.
- Add a Persistent Storage volume mounted at
/data(Coolify → your app → Storages). This is essential — without it, data is lost on every redeploy. - Set
CIVILITY_AUTH_SECRET(andCIVILITY_ADMIN_EMAILSto reach/admin) in Environment Variables. - Deploy and attach a domain.
No separate database resource is needed — that's the point of this template.
Deploy to Fly.io #
Optional. The bundled fly.toml declares a single machine with an attached volume. Delete it if you're not using Fly.
curl -L https://fly.io/install.sh | sh
fly auth login
fly launch --no-deploy --copy-config
fly volumes create civility_data --region iad --size 3 # GB
fly secrets set CIVILITY_AUTH_SECRET="$(openssl rand -hex 32)"
fly deploy
Because the volume pins the app to one machine, do not scale past a single instance. For a scalable Fly deployment, use ../postgres/ with Fly Postgres + Tigris.
Backup #
All state is in the /data volume. Stop the container for a consistent snapshot (SQLite is being written live otherwise):
docker compose stop
docker run --rm -v civility-data:/data -v "$PWD":/backup alpine \
tar -czf /backup/civility-backup-$(date +%Y%m%d).tar.gz -C /data .
docker compose start
For online SQLite backups without stopping, use the sqlite3 .backup command against /data/civility.db from inside the container. See the manual VPS guide → Backup for the broader strategy.
Environment variables #
| Variable | Required | Purpose |
|---|---|---|
PORT |
No (default 8080) |
Bind port. The container binds 0.0.0.0:$PORT. |
DATA_DIR |
No (default /data) |
Directory holding civility.db and blobs/. Must be on the mounted volume. |
CIVILITY_ADMIN_TOKEN |
Optional | Bearer token for the /admin JSON API (scripts). Generate with openssl rand -hex 32. |
CIVILITY_ADMIN_EMAILS |
Optional | Comma-separated account emails granted /admin access via dashboard sign-in. |
CIVILITY_AUTH_SECRET |
Recommended | JWT signing key. Generate once and keep stable. |
OTEL_DENO, OTEL_* |
Optional | Enable OpenTelemetry traces/metrics/logs. See observability. |
Email transport is configured in the admin panel at runtime, not via env.
There is intentionally no DATABASE_URL or S3_* here. To use those, switch to ../postgres/.
No native SQLite library needed #
The adapter uses node:sqlite, the engine compiled into the Deno binary — no FFI, no prebuilt-library download, no libc constraint, so the image can use any base Deno runs on (this one uses alpine). Needs Deno ≥ 2.9; the pinned image qualifies.
See also #
- Deployments overview — pick the right template
- Hybrid (SQLite + S3 blobs) deployment — same DB, blobs in a bucket
- Multi-resource (Postgres + S3) deployment — scaling, managed DB, Coolify
- Manual VPS deployment — systemd + Caddy, backups
- Self-hosting quickstart — local dev with
civ api start - Admin panel (incl. email config) · Observability