Deployment

Production-oriented notes for running Invio reliably.

Images and services

The repo includes a docker-compose file that runs two services:

• Backend: ghcr.io/kittendevv/invio-backend:main
• Frontend: ghcr.io/kittendevv/invio-frontend:main

They communicate via BACKEND_URL (default http://backend:3000).

Environment variables

Backend (required unless defaults are acceptable):

• ADMIN_USER / ADMIN_PASS — bootstrap credentials validated during login
• JWT_SECRET — HMAC secret for admin JWT sessions
• SESSION_TTL_SECONDS — lifetime of issued JWTs (min 300, max 12h)
• DATABASE_PATH — SQLite file path inside the container (default /app/data/invio.db)
• BACKEND_PORT or PORT — container listen port (compose maps host port BACKEND_PORT)
• BASE_URL — used to form share URLs in publish responses
• Security headers: SECURE_HEADERS_DISABLED, ENABLE_HSTS, CONTENT_SECURITY_POLICY
• Demo mode controls: DEMO_MODE, DEMO_DB_PATH, DEMO_RESET_HOURS, DEMO_RESET_ON_START

Frontend:

• PORT — listen port (compose maps via FRONTEND_PORT)
• BACKEND_URL — the backend base URL the frontend talks to
• Auth/session tuning: SESSION_TTL_SECONDS, COOKIE_SECURE
• Security headers: FRONTEND_SECURE_HEADERS_DISABLED, ENABLE_HSTS, FRONTEND_CONTENT_SECURITY_POLICY

Persistence

With the included docker-compose.yml, the backend uses the named volume invio_data mounted at /app/data, which stores:

• SQLite database file (invio.db)
• Installed template assets under /app/data/templates/<id>/<version>/...

Back up the volume for safety. See Reference → Export & Backup for a full export endpoint that bundles DB, JSON dump, and template assets.

Reverse proxy

Put any reverse proxy (Caddy, Nginx, Traefik) in front of the frontend container. Example headers to pass through:

• X-Forwarded-Proto, X-Forwarded-For
• Set appropriate timeouts for PDF generation on larger docs

Caddy example (pseudocode):

invio.example.com {
  reverse_proxy / http://frontend:8000
}

If you want API-only access, you can also expose the backend at another hostname.

Updates

Pull the latest images and restart:

docker compose pull
docker compose up -d

The backend runs schema migrations on startup and keeps built‑in templates up to date.

Demo mode

Set DEMO_MODE=true to enable a writable sandbox that resets on a schedule. Required variables:

• DEMO_DB_PATH — path to a pristine database file mounted into the container
• DATABASE_PATH — active DB file (default /app/data/invio.db)
• DEMO_RESET_HOURS — interval (default 3)
• DEMO_RESET_ON_START — perform a reset at startup (default true)

The server keeps serving while it resets and reinitializes; writes between resets are allowed but not persistent.