Skip to main content

Cluster Deployment Runbook

This runbook covers the deployment of the AlphaSwarm Scholar platform to Kubernetes clusters, including local development clusters and remote production-like environments.

Prerequisites​

  • Access to a Kubernetes cluster (v1.24+).
  • kubectl configured with appropriate context.
  • Docker installed (for local builds).
  • Helm v3+ (optional, for some components).
  • AlphaSwarm CLI installed.

Quick Start: Remote Cluster Deployment​

To deploy to a remote cluster (e.g., 192.168.12.112), follow these steps:

1. Configure Cluster Access​

Ensure your kubeconfig is set up correctly (the deploy scripts below default to KUBECONFIG=/home/julia/.kube/alphaswarm-local.config). There is no setup-cluster-access.sh helper script in the alphaswarm repo; configure kubectl access manually per the connectivity instructions the deploy script prints if it cannot reach the cluster.

2. Run the Deployment Script​

Execute the deployment script on the target machine or from a workstation with access:

./deploy-on-cluster.sh

This script (alphaswarm/deploy-on-cluster.sh) will:

  • Verify Kubernetes access.
  • Create the alphaswarm-scholar namespace.
  • Deploy core databases: PostgreSQL, Redis, Neo4j.
  • Build and deploy the single scholar service (the alphaswarm_learning image); it does not deploy separate API/Worker/Ingester/UI services.

Local Cluster Deployment (Development)​

For local development using k3d, minikube, or Docker Desktop:

1. Deploy the local cluster stack​

alphaswarm/deploy-to-local-cluster.sh takes no --init/--deploy flags — it is a single script that checks cluster connectivity, creates the namespace, deploys PostgreSQL/Redis/Neo4j, and builds and deploys the scholar service in one pass:

./deploy-to-local-cluster.sh

2. Verify Deployment​

kubectl get pods -n alphaswarm-scholar

Configuration​

Environment Variables​

Key variables to configure in your deployment overlay or .env file:

  • ALPHASWARM_ENV: production, staging, or development.
  • ALPHASWARM_API_BASE: External URL of the API.
  • DATABASE_URL: Connection string for PostgreSQL.
  • NEO4J_URI: Connection string for Neo4j.

Cloudflare Tunnel Setup​

If exposing the cluster via Cloudflare: there is no standalone setup-cloudflare-tunnel.sh script in the alphaswarm repo. The deploy scripts (deploy-on-cluster.sh, deploy-to-local-cluster.sh, deploy-scholar-docker.sh) load Cloudflare credentials from ~/.alphaswarm-cf.env if present; configure the tunnel separately via the Cloudflare dashboard or cloudflared CLI.

Post-Deployment Checklist​

  • Verify all pods are in Running state.
  • Check API health: curl https://api.your-domain.com/readyz.
  • Log in to the UI and verify connectivity.
  • Configure monitoring and alerts (Loki/Grafana).
  • Verify database backups are scheduled.

Further Documentation​