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 at minimum:

values.production.yaml
api:
  replicas: 2
  env:
    DATABASE_URL: "postgresql://user:pass@your-db:5432/optio"
    REDIS_URL: "redis://your-redis:6379"
    OPTIO_ENCRYPTION_KEY: "<32-byte-hex-key>"
    PUBLIC_URL: "https://optio.yourcompany.com"

web:
  replicas: 2
  env:
    NEXT_PUBLIC_API_URL: "https://optio.yourcompany.com/api"
    NEXT_PUBLIC_WS_URL: "wss://optio.yourcompany.com"

# Use external managed databases
postgres:
  enabled: false
redis:
  enabled: false

# OAuth (at least one provider)
auth:
  github:
    clientId: "your-github-oauth-client-id"
    clientSecret: "your-github-oauth-client-secret"

ingress:
  enabled: true
  host: optio.yourcompany.com
  tls: true

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.

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