Self-Hosting Impri

Impri is fully self-hostable. docker compose up gives you the complete stack: API server, web inbox, SQLite database, and the watcher scheduler. No licence required, no external services needed to get started.

Requirements

• Docker Engine 24+ and Docker Compose v2
• A machine with at least 256 MB of free RAM (SQLite; a Hetzner CX22 is more than enough)
• (Optional) A domain name and a reverse proxy (Caddy, nginx, Traefik) for HTTPS

Quick start

git clone https://github.com/impri-dev/impri.git
cd impri

# Generate a strong webhook secret (required — do not leave it as "change-me-in-production")
echo "WEBHOOK_SECRET=$(openssl rand -hex 32)" > .env

docker compose up -d

The server is now running:

• API: http://localhost:8484/v1
• Web inbox: http://localhost:8080
• Health check: http://localhost:8484/healthz
• OpenAPI spec: http://localhost:8484/v1/openapi.json

On first start, the bootstrap admin key is printed to the server log. Retrieve it:

docker compose logs server | grep "Admin API Key"

Store this key somewhere safe — it is hashed in the database and will not be shown again.

Environment variables

All configuration is passed via environment variables. The easiest way to manage them is a .env file in the project root (Docker Compose picks it up automatically).

Required

Server

Notifications

Impri can notify you via email (SMTP) and/or ntfy. Both are optional; the server starts without them and falls back to logging the notification.

Email (SMTP):

ntfy (recommended for self-hosters):

ntfy is an open-source push notification service with mobile apps. It works with the public ntfy.sh instance or your own self-hosted ntfy server, and requires no registration for basic use.

Example: to receive notifications at https://ntfy.sh/my-secret-topic-abc123:

NTFY_URL=https://ntfy.sh
NTFY_TOPIC=my-secret-topic-abc123

Install the ntfy app on your phone, subscribe to the topic, and you will receive a push notification for every pending action.

Web push (VAPID) — optional

Browser push notifications for the web inbox. Generate a keypair once and set it in the environment; without these keys the web-push channel is simply off (email / ntfy still work).

npx web-push generate-vapid-keys   # prints a public + private key

Once enabled, open the web inbox and use Enable push notifications in the Notifications section — the browser subscribes and you get a push for every new pending action.

Redis (rate limiter) — optional, multi-instance only

Security

Example .env for a production self-host

WEBHOOK_SECRET=a6f3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4
BASE_URL=https://impri.yourdomain.com

# Notifications via ntfy
NTFY_URL=https://ntfy.sh
NTFY_TOPIC=my-secret-topic-abc123

# Email backup notifications
SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
[email protected]
SMTP_PASS=your-smtp-password
[email protected]
[email protected]

Reverse proxy (HTTPS)

For production use, put a reverse proxy in front that handles TLS. The UI container serves on port 8080 and the API server on 8484. A typical setup proxies both through a single domain:

• https://impri.yourdomain.com → UI (port 8080)
• https://impri.yourdomain.com/v1 → API (port 8484/v1)

Or run them on separate subdomains. The important variable is BASE_URL, which must match the public URL the UI and API are reachable at.

Example Caddy config:

impri.yourdomain.com {
  reverse_proxy /v1/* localhost:8484
  reverse_proxy /* localhost:8080
}

Backups

Impri uses SQLite. The database file is stored in the impri-data Docker volume, mounted at /app/data/impri.db inside the container.

Manual backup:

# Hot backup using SQLite's built-in online backup
docker compose exec server sqlite3 /app/data/impri.db ".backup /app/data/impri-backup-$(date +%Y%m%d).db"

Automated daily backup (cron example):

# /etc/cron.daily/impri-backup
#!/bin/bash
BACKUP_DIR=/var/backups/impri
mkdir -p "$BACKUP_DIR"
docker compose -f /home/impri/docker-compose.yml exec -T server \
  sqlite3 /app/data/impri.db ".backup /tmp/impri-$(date +%Y%m%d).db"
docker compose -f /home/impri/docker-compose.yml cp \
  server:/tmp/impri-$(date +%Y%m%d).db "$BACKUP_DIR/"
# Optionally: rsync to offsite storage

Decisions (what a human approved or rejected) are the most critical data. The database schema stores them in an append-only decisions table with a decisions unique constraint that prevents overwrite.

Upgrading

# Pull the latest images
docker compose pull

# Restart with zero-downtime (the server handles SQLite migrations on startup)
docker compose up -d

There are no manual migration steps for v1 — schema migrations run automatically on startup. Database backups before upgrading are always a good idea.

Monitoring

• Health endpoint: GET /healthz returns {"status":"ok","ts":<unix>} — use it for uptime checks.
• Prometheus metrics: GET /metrics (if enabled in your build — check the deployment).
• Structured logs: the server writes JSON logs via Fastify's built-in logger. API keys are redacted from all log output.
• Error reporting (Sentry) — optional and off by default. Set SENTRY_DSN (server) and/or VITE_SENTRY_DSN (UI, baked in at docker compose build time — see deploy/.env.example) to send unexpected errors to your own Sentry project. Unset means the SDK is never invoked at all. Full details, including exactly what is scrubbed before an event is sent: Observability → Error reporting.

Watcher scheduler

When watchers are enabled (the default), the scheduler polls each active watcher on its configured interval and delivers matching items to your inbox or a webhook. The scheduler runs inside the same server container and requires no external queue.

To disable it (approval inbox only):

DISABLE_WATCHER_SCHEDULER=1

Watcher state is persisted in SQLite. A degraded watcher (3 consecutive failures) is surfaced in the UI and triggers a notification. After 24 hours of failures it is automatically paused.