Production Deployment

Deploy Optio to a Kubernetes cluster for your team using the included Helm chart with managed PostgreSQL and Redis.

Production deployment uses the same Helm chart as local development, configured for external managed services, real OAuth authentication, TLS ingress, and a container registry for agent images.

Prerequisites

• A Kubernetes cluster (EKS, GKE, AKS, or any conformant cluster)
• Helm 3+ (helm version)
• A managed PostgreSQL instance (e.g. RDS, Cloud SQL, Supabase, Neon)
• A managed Redis instance (e.g. ElastiCache, Upstash, Redis Cloud)
• A container registry for agent images (e.g. GHCR, ECR, Docker Hub)
• At least one OAuth provider (GitHub, Google, or GitLab) with a registered application
• metrics-server installed in the cluster
• A domain name with DNS pointing to your cluster’s load balancer

Deployment

1. Generate an encryption key

   Optio encrypts all secrets at rest with AES-256-GCM. Generate a key and keep it somewhere safe — if you lose it, stored secrets (API keys, OAuth tokens) cannot be decrypted.

   openssl rand -hex 32
   

   Store the output. You will pass it as --set encryption.key=<value> during install.

2. Push agent images to your registry

   Build and push the agent image presets to a registry your cluster can pull from:

   # Build all presets
   ./images/build.sh
   
   # Tag and push (example using GHCR)
   docker tag optio-base:latest ghcr.io/your-org/optio-agent-base:latest
   docker tag optio-node:latest ghcr.io/your-org/optio-agent-node:latest
   docker tag optio-python:latest ghcr.io/your-org/optio-agent-python:latest
   docker tag optio-go:latest ghcr.io/your-org/optio-agent-go:latest
   docker tag optio-rust:latest ghcr.io/your-org/optio-agent-rust:latest
   docker tag optio-full:latest ghcr.io/your-org/optio-agent-full:latest
   
   docker push ghcr.io/your-org/optio-agent-base:latest
   # ... repeat for each preset
   

   Set agent.imagePullPolicy to IfNotPresent or Always (not Never) so Kubernetes can pull from the registry.

3. Configure an OAuth provider

   Register an OAuth application with at least one provider. Optio supports GitHub, Google, and GitLab.

   GitHub — go to Settings → Developer settings → OAuth Apps → New OAuth App:

   • Homepage URL: https://optio.example.com
   • Authorization callback URL: https://optio.example.com/api/auth/github/callback

   Note the Client ID and Client Secret.

   The callback URL must match API_PUBLIC_URL exactly, including the /api/auth/<provider>/callback path. If these do not match, OAuth login will fail with a redirect URI mismatch error.

4. Install the Helm chart

   helm install optio helm/optio \
     --namespace optio \
     --create-namespace \
     --set encryption.key=$(openssl rand -hex 32) \
     --set postgresql.enabled=false \
     --set externalDatabase.url="postgres://user:pass@your-db-host:5432/optio" \
     --set redis.enabled=false \
     --set externalRedis.url="redis://your-redis-host:6379" \
     --set ingress.enabled=true \
     --set ingress.hosts[0].host=optio.example.com \
     --set auth.github.clientId=your-github-client-id \
     --set auth.github.clientSecret=your-github-client-secret \
     --set agent.image.repository=ghcr.io/your-org/optio-agent-base \
     --set agent.imagePullPolicy=IfNotPresent
   

   Replace values with your actual database URL, Redis URL, domain, OAuth credentials, and agent image repository.

   Do not pass --set auth.disabled=true in production. Optio requires OAuth authentication to be active. If auth.disabled is set, any user can access the deployment without logging in.

5. Set the GitHub token secret

   Optio needs a GitHub token for PR watching, issue sync, and repository detection. After the API pod is running, add it via the web UI (Settings → Secrets) or directly:

   # The setup wizard in the web UI will prompt for this on first run
   # Navigate to: https://optio.example.com/setup
   

   The GITHUB_TOKEN secret requires repo scope for private repositories and public_repo for public ones.

6. Verify the deployment

   Check that all pods are running:

   kubectl get pods -n optio
   

   Expected output shows optio-api-*, optio-web-*, and (if using in-cluster databases) optio-postgres-* and optio-redis-* pods all in Running state.

   Open https://optio.example.com — you should be redirected to the login page.

Production checklist

Review each item before going live:

#	Item	Notes
1	Encryption key generated	openssl rand -hex 32; store it securely
2	OAuth provider configured	At least one of GitHub, Google, or GitLab
3	Auth bypass disabled	auth.disabled must be false or unset
4	External PostgreSQL	postgresql.enabled=false + externalDatabase.url
5	External Redis	redis.enabled=false + externalRedis.url
6	Public URLs set	API_PUBLIC_URL and WEB_PUBLIC_URL match your domain
7	Ingress with TLS	ingress.enabled=true with cert-manager or manual TLS
8	Agent image in registry	agent.imagePullPolicy=IfNotPresent or Always
9	GitHub token secret set	Required for PR watching, issue sync, repo detection
10	Resource limits tuned	Adjust api.resources and agent PVC size for your workload
11	metrics-server installed	Required for resource usage display in the cluster view

TLS with cert-manager

If cert-manager is installed in your cluster, enable automatic certificate provisioning:

helm upgrade optio helm/optio -n optio --reuse-values \
  --set ingress.certManager.enabled=true \
  --set ingress.certManager.clusterIssuer=letsencrypt-prod

For manual TLS certificate management, configure the ingress.tls field directly in a values file:

ingress:
  enabled: true
  tls:
    - secretName: optio-tls
      hosts:
        - optio.example.com

RBAC requirements

The Helm chart creates a ServiceAccount and Role for the API server automatically. The API server needs these permissions to manage agent pods:

• pods: get, list, watch, create, delete
• pods/exec: create (for running agents in pods)
• pods/log: get
• secrets: get, list, create, update, delete
• persistentvolumeclaims: get, list, create, delete
• services: get, list, create, delete
• events: get, list, watch

A separate ClusterRole covers read access to nodes, namespaces, and metrics for the cluster health view. Do not remove or restrict these permissions — the API server will fail to provision agent pods.

Updating

To apply new configuration changes or upgrade to a newer version:

# Apply changes while preserving existing values
helm upgrade optio helm/optio -n optio --reuse-values

To trigger a rolling restart of the API and web servers (e.g. after updating a secret or environment variable):

kubectl rollout restart deployment/optio-api deployment/optio-web -n optio

Troubleshooting

OAuth login fails with redirect URI mismatch

• Verify that the callback URL registered with the OAuth provider exactly matches {API_PUBLIC_URL}/api/auth/<provider>/callback
• Set API_PUBLIC_URL explicitly in your Helm values if it is not being inferred correctly
• Check for trailing slashes or http vs https mismatches

Agent pods fail to start (ImagePullBackOff)

• Confirm the agent image is pushed to your registry and the tag is correct
• Check that imagePullSecrets is configured if your registry requires authentication
• Verify agent.imagePullPolicy is IfNotPresent or Always (not Never)

API pod fails to connect to the database

• Confirm externalDatabase.url is formatted correctly: postgres://user:pass@host:5432/dbname
• Test connectivity from within the cluster: kubectl run -it --rm debug --image=postgres:16 --restart=Never -n optio -- psql "$DATABASE_URL"
• Check that the database allows connections from the cluster’s IP range

Pod health events show OOM kills

• Increase resource limits for agent pods via the image preset or Helm values (agent.pvc.size, API resource limits)
• Check pod_health_events via the cluster view in the web UI for crash history
• The cleanup worker automatically fails tasks on dead pods and recreates pods on the next task