Self-hosting Oligon Receipts

What you get

• Full backend container image (FastAPI + arq + alembic).
• Helm chart and Docker Compose stack.
• Tuned Postgres, Valkey, and Caddy configs (the same ones we run in prod — see infra/ in this repo).
• A perpetual license for the SDKs (MIT, no strings).
• Quarterly model updates (Anthropic Claude / OpenAI GPT-4o Vision).
• Direct Slack channel with the engineering team.

Requirements

The model API call is the only external dependency. Storage (R2 in our managed offering) can be swapped for any S3-compatible bucket or local disk.

Architecture

Identical to the managed product:

Caddy → FastAPI (gunicorn uvicorn 4w) → Postgres + PgBouncer + Valkey
                                     ↘ arq workers (jobs)
                                     ↘ S3-compatible object store

See the architecture diagram in the repo README (opens in a new tab).

Deployment

Two-step bootstrap on a fresh Ubuntu 22.04 host:

./scripts/setup_oracle_vm.sh       # provisions Postgres, Valkey, Caddy, systemd
./scripts/deploy.sh                # builds and rolls out the backend

The same scripts power oligontech.com's own prod. They are idempotent — you can re-run setup to apply config changes without downtime.

Upgrades

We publish a oligon/receipts:vX.Y.Z image weekly. Pin to a minor version (v0.3.x) and run deploy.sh whenever you want the latest patch. Migrations are applied with alembic upgrade head and never require a downtime window — schema changes go through two-phase deploys.

Air-gapped installations

Possible but requires a self-hosted vision model. We have customers running on-prem with Qwen2-VL-72B (opens in a new tab) or InternVL2-Llama3-76B (opens in a new tab) — extraction quality is ~95% of Claude Sonnet 4.6 on Brazilian NFCe and ~92% on US hand-written receipts. Contact us for a benchmark report.