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

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:

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

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 #

  1. + New → Application, point it at the repo holding this directory, choose the Dockerfile (or Docker Compose) build pack.
  2. Add a Persistent Storage volume mounted at /data (Coolify → your app → Storages). This is essential — without it, the database is lost on every redeploy.
  3. Set S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY, S3_REGION, CIVILITY_AUTH_SECRET, and CIVILITY_ADMIN_EMAILS (to reach /admin) in Environment Variables.
  4. 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 /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-db-$(date +%Y%m%d).tar.gz -C /data .
    docker compose start
    

    For online backups without stopping, use the sqlite3 .backup command against /data/civility.db from 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 #