Skip to content

Production Deployment

Sparrow is a single Go binary backed by PostgreSQL. It runs on any container platform – this page uses Kubernetes as the worked example, but the same configuration applies to ECS, Cloud Run, Fly.io, or a plain Docker host behind a reverse proxy.

The Docker Compose (local) page covers a zero-config setup for trying Sparrow on your own machine. Everything below assumes you are deploying for real use.

Set these environment variables on the Sparrow container. Keep them in a secret manager or Kubernetes Secret – never bake them into images or check them into source control.

Variable How to generate Notes
SPARROW_ENVIRONMENT production The server refuses to start without SPARROW_API_KEY and blocks cross-origin browser requests by default.
SPARROW_API_KEY openssl rand -hex 32 Master key for /v1 and the UI sign-in prompt. Must be at least 32 characters in production (the server refuses to start otherwise).
SPARROW_ENCRYPTION_KEYS main=$(openssl rand -hex 32) Keyring for envelope encryption; each key is 32 random bytes as 64 hex chars. See key rotation.
SPARROW_ENCRYPTION_PRIMARY_KEY_ID main Which key ID in the keyring is used for new encryption.
DATABASE_URL — PostgreSQL connection string. Use sslmode=require or sslmode=verify-full when the database is not on localhost.
SPARROW_SERVE_UI true or false Serve the embedded web dashboard.

Other variables (SPARROW_LOG_LEVEL, SPARROW_ALLOWED_NETWORKS, SPARROW_CORS_ALLOWED_ORIGINS, SPARROW_EVENT_RETENTION_DAYS, SPARROW_AUTO_DISABLE_AFTER, SPARROW_METRICS_ENABLED, SPARROW_SHUTDOWN_TIMEOUT, SPARROW_AI_ENABLED, OTEL_EXPORTER_OTLP_ENDPOINT, etc.) are documented in Configuration.

apiVersion: v1
kind: Secret
metadata:
name: sparrow
type: Opaque
stringData:
SPARROW_ENVIRONMENT: production
SPARROW_API_KEY: "<openssl rand -hex 32>"
SPARROW_ENCRYPTION_KEYS: "main=<openssl rand -hex 32>"
SPARROW_ENCRYPTION_PRIMARY_KEY_ID: main
DATABASE_URL: "postgres://sparrow:<password>@db.internal:5432/sparrow?sslmode=require"
SPARROW_SERVE_UI: "true"

Replace the placeholder values with real secrets. In a managed cluster, use an external secrets operator (AWS Secrets Manager, Vault, etc.) instead of inline stringData.

apiVersion: apps/v1
kind: Deployment
metadata:
name: sparrow
spec:
replicas: 2 # safe: migrations use Postgres advisory locks; River queue is Postgres-backed
# each replica uses up to 75 Postgres connections (see below)
selector:
matchLabels:
app: sparrow
template:
metadata:
labels:
app: sparrow
spec:
terminationGracePeriodSeconds: 30 # > preStop sleep + SPARROW_SHUTDOWN_TIMEOUT (default 10s)
containers:
- name: sparrow
image: ghcr.io/sarathsp06/sparrow:X.Y.Z # pin a release (no leading v), not latest
ports:
- containerPort: 8080
envFrom:
- secretRef:
name: sparrow
securityContext:
runAsNonRoot: true
runAsUser: 65532 # distroless nonroot
readOnlyRootFilesystem: true
allowPrivilegeEscalation: false
capabilities:
drop: [ALL]
seccompProfile:
type: RuntimeDefault
livenessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 5
periodSeconds: 15
readinessProbe:
httpGet:
path: /ready
port: 8080
initialDelaySeconds: 3
periodSeconds: 10
lifecycle:
preStop:
sleep:
seconds: 10 # let endpoints drop the pod before shutdown starts (see below)
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: "1"
memory: 512Mi

Each replica opens up to 75 Postgres connections, so two replicas already exceed Postgres’ default max_connections = 100. Size it for 75 × (replicas + maxSurge) plus headroom; see the connection budget. Large instances should also run migrations in a pre-deploy Job.

On SIGTERM (or SIGINT) Sparrow marks itself not ready and starts shutting down at once. /ready turns 503, but the HTTP listener closes immediately after, so in practice a readiness probe rarely sees the 503 before connections are refused. Kubernetes removes a pod from Service endpoints asynchronously, and requests routed to it in that gap fail. Give the endpoints time to update before the signal reaches Sparrow with a preStop sleep of 5-10 seconds, as in the Deployment above. The image is distroless and has no shell or sleep binary, so use the built-in sleep action (Kubernetes 1.30+) rather than exec: [sleep, ...].

SPARROW_SHUTDOWN_TIMEOUT (default 10s) is one budget for the whole shutdown: in-flight HTTP requests finish first, then the queue stops taking jobs and waits for running deliveries. Jobs still running when the budget runs out are cancelled and retried later by another replica, so an attempt can be repeated. Kubernetes counts the preStop hook against terminationGracePeriodSeconds, so set it above the sum: with a 10 second preStop sleep and the default 10 second shutdown timeout, 30 seconds leaves room. If the grace period runs out first, the kubelet kills the process mid-shutdown.

apiVersion: v1
kind: Service
metadata:
name: sparrow
spec:
type: ClusterIP
selector:
app: sparrow
ports:
- port: 8080
targetPort: 8080

Sparrow is designed to run behind a VPN. Expose it through an internal Ingress or LoadBalancer on the VPN network, with TLS terminated at the ingress controller. Never use a public-facing LoadBalancer unless you also put an authenticating proxy in front (see Securing Sparrow).

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: sparrow
annotations:
# Cloud-specific: mark as internal-only
# AWS: alb.ingress.kubernetes.io/scheme: internal
# GCP: networking.gke.io/internal: "true"
spec:
rules:
- host: sparrow.internal.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: sparrow
port:
number: 8080
tls:
- hosts: [sparrow.internal.example.com]
secretName: sparrow-tls

Restrict inbound traffic to the ingress controller and deny sensitive egress destinations:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: sparrow
spec:
podSelector:
matchLabels:
app: sparrow
policyTypes: [Ingress, Egress]
ingress:
- from:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: ingress-nginx # your ingress controller's namespace
ports:
- port: 8080
egress:
# Allow DNS
- to:
- namespaceSelector: {}
ports:
- port: 53
protocol: UDP
- port: 53
protocol: TCP
# Allow PostgreSQL
- to:
- ipBlock:
cidr: 10.0.0.0/8 # adjust to your DB subnet
ports:
- port: 5432
# Webhook delivery: any destination and port (receivers often listen on
# 8080, 8443, ...), except the cloud metadata endpoint. Sparrow blocks it
# too; this is defence in depth. Tighten to your receivers' CIDRs/ports
# if you know them.
- to:
- ipBlock:
cidr: 0.0.0.0/0
except:
- 169.254.169.254/32
ports:
- protocol: TCP

Adjust the namespace label and database CIDR to match your cluster. Which internal webhook targets are reachable is controlled by SPARROW_ALLOWED_NETWORKS (below), so the policy does not need to repeat it.

Sparrow’s SSRF check runs at connect time in every mode – it is never skipped. By default, private, loopback, and link-local addresses are blocked as webhook targets.

Cloud metadata endpoints are always blocked, even with SPARROW_ALLOW_PRIVATE_NETWORKS=true: 169.254.169.254, 169.254.170.2, 169.254.170.23, 100.100.100.200, fd00:ec2::254 and fd00:ec2::23, including their IPv4-mapped, 6to4, NAT64, IPv4-compatible, IPv4-translated and Teredo forms. They hand out cloud credentials; list one in SPARROW_ALLOWED_NETWORKS only if you truly mean to deliver there.

The default blocklist also covers 0.0.0.0/8, local-use NAT64 (64:ff9b:1::/48), the reserved IPv6 ranges 100::/64, 2001:2::/48, 2001:db8::/32 and fec0::/10, and IPv6 addresses that embed a restricted IPv4 address: 6to4 (2002::/16), NAT64 (64:ff9b::/96), IPv4-compatible (::/96), IPv4-translated (::ffff:0:0:0/96) and Teredo (2001::/32). Public destinations in those forms still work.

To deliver webhooks to internal services (the common case on a VPN), use SPARROW_ALLOWED_NETWORKS:

Terminal window
# Allow webhook deliveries to your VPN subnet
SPARROW_ALLOWED_NETWORKS=10.20.0.0/16,fd12::/48

Only the listed CIDRs are opened; loopback, cloud metadata, and other private ranges stay blocked. Invalid entries fail startup. When an allowlist is set, .internal and .local hostnames are no longer blocked by name; their resolved addresses are checked instead.

SPARROW_ALLOW_PRIVATE_NETWORKS=true opens all private IPs (except cloud metadata) and is meant for local development and testing, not production. A Kubernetes egress NetworkPolicy (above) is still good defence in depth.

The server never writes SPARROW_API_KEY into the UI. When SPARROW_API_KEY is set, the embedded dashboard shows a Sign in to Sparrow prompt on the first 401. Operators can:

Give each person and CI job their own access token instead of sharing SPARROW_API_KEY. Use invites for people (sparrow invite alice), direct token creation for machines (sparrow tokens create --name ci-deploy).

  • SPARROW_ENVIRONMENT=production and SPARROW_API_KEY set (at least 32 characters; openssl rand -hex 32).
  • Encryption keyring (SPARROW_ENCRYPTION_KEYS + SPARROW_ENCRYPTION_PRIMARY_KEY_ID) generated with openssl rand -hex 32 and stored in a secret manager. With SPARROW_ENVIRONMENT=production Sparrow refuses to start with the all-zeros development key. Back it up – lose it and encrypted webhook secrets are unrecoverable.
  • DATABASE_URL points to a managed Postgres with sslmode=require or stronger.
  • Image tag pinned to a release (not latest).
  • Container runs as non-root (UID 65532), read-only filesystem, no privilege escalation, all capabilities dropped.
  • Liveness (/health) and readiness (/ready) probes configured. /health only says the process is up, so a database outage never restarts pods; /ready checks the database and answers 503 from the moment shutdown starts. Add a preStop sleep and keep terminationGracePeriodSeconds above the preStop sleep plus SPARROW_SHUTDOWN_TIMEOUT; see Graceful shutdown.
  • Prometheus scraping /metrics (or OTLP export configured), with alerts on delivery success rate, sparrow_queue_jobs backlog, and sparrow_webhooks_auto_disabled_total. /metrics needs no API key: keep it off public networks, or set SPARROW_METRICS_ENABLED=false.
  • SPARROW_AUTO_DISABLE_AFTER reviewed (default 5 days of failures pauses a webhook; deliveries are held, not dropped) and an alert config opted into sparrow.webhook.disabled.
  • Exposed only through an internal ingress or VPN – never a public LoadBalancer.
  • TLS terminated at the ingress controller or reverse proxy.
  • SPARROW_CORS_ALLOWED_ORIGINS set if the UI is hosted on a different origin.
  • Use SPARROW_ALLOWED_NETWORKS (not SPARROW_ALLOW_PRIVATE_NETWORKS) for internal webhook targets. Cloud metadata endpoints are always blocked.
  • SPARROW_EVENT_RETENTION_DAYS set if payloads carry regulated data.
  • SPARROW_LOG_LEVEL chosen: the default info writes a line for every event and delivery; warn keeps only problems and is lighter on a busy instance.
  • Each person and CI job uses their own access token, not the master key. Tokens expire after SPARROW_TOKEN_DEFAULT_TTL (90 days) unless created with --ttl never.
  • Revoke tokens when someone leaves or a machine credential is retired.
  • SPARROW_API_KEY minimum length. With SPARROW_ENVIRONMENT=production, the server now requires SPARROW_API_KEY to be at least 32 characters. If your existing key is shorter, generate a new one with openssl rand -hex 32 before upgrading. Outside production mode, a short key logs a warning but still works.
  • Cloud metadata always blocked. Cloud metadata endpoints (169.254.169.254, 169.254.170.2, etc.) are now blocked even when SPARROW_ALLOW_PRIVATE_NETWORKS=true. If you need to reach one deliberately, list it in SPARROW_ALLOWED_NETWORKS.
  • Tenant-wide tokens expire by default. New tenant-wide tokens, browser sign-ins and invite-created tokens now expire after SPARROW_TOKEN_DEFAULT_TTL (90 days) unless created with an explicit TTL or never_expires (sparrow tokens create --ttl never). Existing tokens keep their lifetime. Set SPARROW_TOKEN_DEFAULT_TTL=0 to keep the old never-expiring default.
  • Custom header validation. Webhook headers are now validated on save. Invalid HTTP token names, CR/LF or control characters in values, values over 8 KiB, and reserved framing headers (Host, Content-Length, Transfer-Encoding, Connection, Keep-Alive, Proxy-Connection, TE, Trailer, Upgrade) are rejected with 400. Existing webhooks keep delivering: a reserved framing header stored before this check is skipped at delivery (it never had an effect), and the webhook only needs fixing the next time its headers are updated.