Browse the docs

Operate

Deployment

Offloader V1 is a customer-run container. The product ships an image, documented env vars, mounted config conventions, health checks, metrics, and smoke tests. Customers decide how to run it on their servers, Kubernetes clusters, Nomad clusters, ECS tasks, VMs, or other internal platforms.

Runtime shape

product traffic -> API port      -> endpoint API keys and tenant enforcement
operators       -> admin port    -> health, readiness, metrics, diagnostics, docs

The admin port is not an identity product. Customers expose it only through their own network, proxy, firewall, IAM, SSO, or RBAC controls.

Config comes from OFFLOADER_CONFIG: either a mounted directory (a ConfigMap/volume with offloader.yml + datasets//endpoints//keys/) or a gs://… bucket prefix fetched at boot (fully stateless). With OFFLOADER_CONFIG_SYNC_INTERVAL set, bucket changes hot-reload with no restart — see the config guide.

Required examples

  • Single-node docker run.
  • Docker Compose with a mounted cache volume.
  • Kubernetes Deployment, Service, ConfigMap, Secret, and PersistentVolumeClaim.
  • Prometheus scrape config for the admin port.
  • Rollback to previous image.
  • Cache quarantine and rebuild.

Rollout verification and rollback

Deploy the published, signed image (ghcr.io/andrewdryga/offloader:<version> — pull it, don't build it), then verify the running instance. dev/scripts/deploy-check.sh is the reusable shape a customer's deployment system can wrap around a freshly-deployed instance (contributors can build-and-verify locally in one step with make deploy-check):

  1. Wait for the admin /ready to return 200 (it stays 503 until a snapshot is materialized, so traffic is held until the instance can actually serve).
  2. Confirm /live, /status, /metrics, and authenticated /diagnostics.
  3. Call one real endpoint with a known key and assert snapshot_id + freshness.
  4. Confirm the admin surface is NOT reachable on the API port.

If a check fails, roll back:

  • Bad image or config — redeploy the previous image tag (pin versions; never :latest). Health returns immediately; there is no schema migration to undo.
  • Bad snapshot — the gateway never swaps in a snapshot that fails validation or compatibility, so serving is already protected. To revert a good-but-wrong snapshot, roll the dataset back to its previous good snapshot (see runbooks → "Rollback to previous snapshot").

Non-goals

  • No hosted Offloader cloud.
  • No Terraform module for a specific provider in V1.
  • No RBAC, SSO, organization management, or team management.
  • No fleet management portal.