Installation

Optio runs on Kubernetes. You can run it locally with Docker Desktop or deploy to a production cluster with the Helm chart.

Local Development

The quickest path uses Docker Desktop's built-in Kubernetes cluster.

Prerequisites

  • Docker Desktop with Kubernetes enabled (Settings → Kubernetes → Enable)
  • Node.js 22+ and pnpm 10+
  • Helm 3+ and kubectl

Automated Setup

terminal
git clone https://github.com/jonwiggins/optio.git
cd optio
./scripts/setup-local.sh

The setup script performs the following:

  1. Checks all prerequisites are installed
  2. Runs pnpm install
  3. Builds all agent images (base, node, python, go, rust, full)
  4. Builds API and web Docker images
  5. Installs the Kubernetes metrics-server
  6. Deploys via Helm with NodePort services (API: 30400, Web: 30310)

Tip

After the initial setup, use ./scripts/update-local.sh to pull the latest changes, rebuild, and redeploy without starting from scratch.

Hot Reload (API + Web)

For iterating on the API or web UI without rebuilding Docker images:

terminal
# Start API and web with hot reload
pnpm dev

# Or individually
pnpm dev:api   # Fastify API on :4000
pnpm dev:web   # Next.js on :3100

Info

When running locally with pnpm dev, you still need Kubernetes running for pod provisioning. The API connects to K8s via kubectl context.

Production Deployment

For production, deploy the Helm chart to your Kubernetes cluster. Images are published to GitHub Container Registry (GHCR) on each release.

Helm Install

terminal
# Add the Optio Helm repository
helm install optio oci://ghcr.io/jonwiggins/optio/helm/optio \
  -f values.production.yaml \
  --namespace optio \
  --create-namespace

Key Production Settings

Create a values.production.yaml with references to Secrets you have already provisioned. Start from helm/optio/values.production.yaml for the complete ingress and resource settings:

values.production.yaml
publicUrl: https://optio.example.com
api:
  replicas: 1
  strategy:
    type: Recreate
  autoscaling:
    enabled: false
postgresql:
  enabled: false
redis:
  enabled: false
auth:
  disabled: false
existingSecrets:
  DATABASE_URL: { name: optio-runtime, key: database-url }
  REDIS_URL: { name: optio-runtime, key: redis-url }
  OPTIO_ENCRYPTION_KEY: { name: optio-runtime, key: encryption-key }
  GOOGLE_OAUTH_CLIENT_ID: { name: optio-sign-in, key: client-id }
  GOOGLE_OAUTH_CLIENT_SECRET: { name: optio-sign-in, key: client-secret }
# Add your ingress, TLS, and storage settings from the production example.

Warning

Always use managed PostgreSQL and Redis in production. The built-in instances are single-node with no replication and are intended for development only. The combined API/web pod currently requires one replica and Recreate upgrades; agent pods scale independently.

See the Deployment guide for the full production checklist and the Configuration reference for all available Helm values.