Connected apps with 3rd-party data hosts jsr.io/@civility
6.7 kB · 141 lines
Markdown
at main

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:

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 #

  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, data is lost on every redeploy.
  3. Set 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 — 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 #