Skip to main content

Redeploy AlphaSwarm local alpha and admin

This runbook covers two targets:

  • alpha.alpha-swarm.ai: Ubuntu-hosted alpha platform reached through the Cloudflare tunnel.
  • admin.alpha-swarm.ai: public admin deployment, rebuilt by GitHub Actions and rolled on AWS ECS Fargate.

Safety rules​

  • Never print kubeconfigs, bearer tokens, Cloudflare tokens, ECR login output, or Authorization headers.
  • Keep admin.alpha-swarm.ai as the primary admin target. The local alphaswarm-admin-api deployment is dev-only.
  • Prefer Git bundles when the Ubuntu host cannot authenticate to GitHub.
  • Do not bypass the GitHub Actions deploy path for public admin unless an incident commander approves an emergency rollback.

Ubuntu-hosted alpha platform​

Preflight​

kubectl config current-context
kubectl get deploy -A
ssh julia@192.168.12.112 'docker --context default version && k3d cluster list'

Expected context: k3d-alphaswarm-local.

Generate a plan​

alphaswarm-cli deploy local-alpha plan --output json

For UI only:

alphaswarm-cli deploy local-alpha plan --component ui

UI rebuild pattern​

The Ubuntu host may not have GitHub credentials. In that case:

git -C ../alphaswarm_ui fetch origin development
git -C ../alphaswarm_ui bundle create /tmp/alphaswarm_ui_development.bundle origin/development
scp /tmp/alphaswarm_ui_development.bundle julia@192.168.12.112:/tmp/alphaswarm_ui_development.bundle

On the Ubuntu host:

cd /home/julia/asw_ui_deploy
git stash push -u -m alpha-hotfixes-before-redeploy || true
git fetch /tmp/alphaswarm_ui_development.bundle origin/development:refs/remotes/origin/development
git merge --ff-only origin/development
git stash pop || true
docker --context default build -t alphaswarm-ui:alpha .
DOCKER_HOST=unix:///var/run/docker.sock k3d image import -c alphaswarm-local alphaswarm-ui:alpha
KUBECONFIG=$HOME/.kube/alphaswarm-local.config kubectl -n alphaswarm-ui rollout restart deploy/alphaswarm-ui-alpha
KUBECONFIG=$HOME/.kube/alphaswarm-local.config kubectl -n alphaswarm-ui rollout status deploy/alphaswarm-ui-alpha --timeout=180s

Admin API local dev rebuild​

Build alphaswarm-admin-api:local from alphaswarm_admin plus vendored alphaswarm_core, import it into k3d, and roll alphaswarm-admin-api.

The local admin API runs with:

  • ALPHASWARM_ADMIN_AUTH_REQUIRED=false
  • ALPHASWARM_ADMIN_ALLOW_ANONYMOUS_DEV=true
  • ALPHASWARM_ADMIN_DEV_FIXTURES=true

This is only for local testing.

Smoke tests​

curl -fsS -I -H "Host: alpha.alpha-swarm.ai" http://192.168.12.112:3000/api/healthz
kubectl -n alphaswarm-ui get deploy,pods
kubectl -n alphaswarm-admin run admin-health-check --rm -i --restart=Never --image=curlimages/curl:8.16.0 --command -- curl -fsS http://alphaswarm-admin-api.alphaswarm-admin.svc.cluster.local:8900/admin/health

Public admin​

Deploy​

The public admin target is https://admin.alpha-swarm.ai. It is rebuilt and rolled by alphaswarm_admin GitHub Actions:

gh workflow run build-publish.yml --ref <branch> --repo Alpha-Swarm-ai/alphaswarm_admin

Monitor:

gh run view <run-id> --repo Alpha-Swarm-ai/alphaswarm_admin --json status,conclusion,jobs

Verify:

curl -fsS https://admin.alpha-swarm.ai/admin/health
curl -fsS -I https://admin.alpha-swarm.ai/login

Known failure modes​

Ubuntu host cannot fetch GitHub​

Use a Git bundle from a machine that can fetch the private repository. Do not copy GitHub credentials onto the Ubuntu host.

Private split package resolution fails​

If image builds fail resolving alphaswarm-core or alphaswarm-agents, vendor the sibling source into the build context and install it before the package that depends on it.

Chainguard pinned Python tag is unavailable​

Use an available Python 3.11 runtime base until the dependency set supports the newer Python wheel ecosystem. Avoid Python 3.14 for the monolith API image while pyarrow and ML dependencies are sensitive to wheel availability.

Public wheel downloads fail​

Retry once if the error is DNS or transient PyPI connectivity. If retries fail, stop and report the exact package and URL without adding broad dependency changes.