Civility on Docker — SQLite + S3 (hybrid) #
A middle ground between the other two Docker templates: one container, one small volume, one bucket. The database (SQLite via @civility/hono/db/sqlite) lives on a mounted volume, but blobs go to an external S3-compatible bucket (Cloudflare R2 recommended).
Civility container (this template)
│
├─── /data volume (SQLite database only — stays small)
│
└─── S3 bucket (blobs → R2 / AWS / Hetzner / Tigris / MinIO)
Use this when ../sqlite/ fits your traffic but not your storage: blobs outgrowing the VPS disk, or wanting them on cheap durable storage behind a CDN (S3_CDN_URL_BASE). No Postgres resource to provision, and the volume holds only the database file, so snapshots stay fast.
Same trade-off as sqlite: single-instance only. For horizontal scaling use ../postgres/.
Files in this directory #
| File | Purpose |
|---|---|
main.ts |
Entry point: SQLite DB under DATA_DIR, blobs in S3. |
Dockerfile |
Alpine-based build — SQLite ships inside the Deno binary. |
docker-compose.yml |
Production: one service + one volume, attaches to your bucket. |
docker-compose.local.yml |
Optional: bundled MinIO for local development. |
deno.json |
Pins @civility/hono. |
.env.example |
Environment variables, documented. |
fly.toml |
Optional, platform-specific: only needed to deploy to Fly.io. |
Quick start #
Bring your own bucket (R2, AWS, Hetzner, Backblaze, Tigris, ...):
cp .env.example .env
# Fill in S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY, then:
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.
Local development (bundled MinIO) #
No external bucket handy? docker-compose.local.yml brings up Civility + MinIO wired together:
cp .env.example .env
docker compose -f docker-compose.local.yml up --build
- Dashboard: http://localhost:8080/dashboard
- MinIO console: http://localhost:9001 (
minioadmin/minioadmin)
A one-shot minio-init container auto-creates the civility-blobs bucket. Tear down and wipe volumes with docker compose -f docker-compose.local.yml down -v.
Run with plain Docker #
docker build -t civility-sqlite-s3 .
docker run -d --name civility -p 8080:8080 \
-v civility-data:/data \
-e S3_ENDPOINT='<account>.r2.cloudflarestorage.com' \
-e S3_BUCKET='civility-blobs' \
-e S3_ACCESS_KEY='...' -e S3_SECRET_KEY='...' -e S3_REGION='auto' \
-e CIVILITY_AUTH_SECRET='...' \
-e CIVILITY_ADMIN_EMAILS='you@example.org' \
--restart unless-stopped \
civility-sqlite-s3
Durable state is split in two: the civility-data volume (database) and the bucket (blobs). Back up both to back up the whole instance.
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, the database is lost on every redeploy. - Set
S3_ENDPOINT,S3_BUCKET,S3_ACCESS_KEY,S3_SECRET_KEY,S3_REGION,CIVILITY_AUTH_SECRET, andCIVILITY_ADMIN_EMAILS(to reach/admin) in Environment Variables. - Deploy and attach a domain.
No separate database resource is needed — only the bucket, which you create at your storage provider (Coolify itself can also host a MinIO resource if you want everything on one box).
Deploy to Fly.io #
Optional. The bundled fly.toml declares a single machine with a small attached volume; blobs go to Tigris (Fly's S3) or any external bucket. 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 1 # GB — DB only, stays small
# Blob storage: Tigris (Fly's S3) — or skip and use external R2
fly storage create
# Tigris sets AWS_* secrets; remap them to S3_* names:
fly secrets set \
S3_ENDPOINT="$(fly ssh console -C 'printenv AWS_ENDPOINT_URL_S3' | tr -d '\r' | sed 's|https://||')" \
S3_BUCKET="$(fly ssh console -C 'printenv BUCKET_NAME' | tr -d '\r')" \
S3_ACCESS_KEY="$(fly ssh console -C 'printenv AWS_ACCESS_KEY_ID' | tr -d '\r')" \
S3_SECRET_KEY="$(fly ssh console -C 'printenv AWS_SECRET_ACCESS_KEY' | tr -d '\r')" \
S3_REGION="auto"
fly secrets set CIVILITY_AUTH_SECRET="$(openssl rand -hex 32)" CIVILITY_ADMIN_EMAILS="you@example.org"
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 #
State is split across two places:
-
Database — the
/datavolume. 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-db-$(date +%Y%m%d).tar.gz -C /data . docker compose startFor online backups without stopping, use the
sqlite3 .backupcommand against/data/civility.dbfrom inside the container. The volume holds only the DB file, so snapshots are much smaller than in the plain sqlite template. -
Blobs — the bucket. Use your provider's replication/versioning, or sync it periodically (
rclone sync,aws s3 sync,mc mirror).
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. Must be on the mounted volume. |
S3_ENDPOINT |
Yes (prod) | S3-compatible endpoint hostname (no https://). Absent → filesystem blobs under DATA_DIR (local dev only). |
S3_BUCKET |
If S3 | Bucket name. |
S3_ACCESS_KEY |
If S3 | Access key ID. |
S3_SECRET_KEY |
If S3 | Secret access key. |
S3_REGION |
Sometimes | auto for R2/Tigris, us-east-1 for MinIO, a real region for AWS. |
S3_CDN_URL_BASE |
Optional | Public CDN prefix for blobs. |
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 here. For Postgres, switch to ../postgres/.
No native SQLite library needed #
Since @civility/hono@0.5.1 the SQLite adapter uses node:sqlite — the SQLite engine compiled into the Deno binary itself. There is no FFI, no prebuilt-library download, and no libc constraint, so the image can be any base Deno runs on (this template uses alpine). The only requirement is a reasonably recent Deno (the pinned image qualifies; for bare-metal runs, Deno ≥ 2.9 is verified).
See also #
- Deployments overview — pick the right template
- Single-resource (sqlite + fs) deployment — no bucket, everything on one volume
- Multi-resource (Postgres + S3) deployment — horizontal scaling, managed DB
- Manual VPS deployment — systemd + Caddy, backups, S3 provider table
- Self-hosting quickstart — local dev with
civ api start - Admin panel (incl. email config) · Observability