Skip to main content

Helm Quickstart

This guide installs Alexandria EE onto a Kubernetes cluster (GKE Autopilot, EKS, AKS, or any conformant cluster) using the bundled Helm chart.

Prerequisites​

  • Kubernetes ≥ 1.27 with a default StorageClass
  • helm ≥ 3.12 and kubectl configured against the target cluster
  • An external Postgres instance reachable from the cluster (Cloud SQL, RDS, or self-managed)
  • A valid Alexandria EE license key

1. Pull the chart​

The chart lives in this repo at k8s/helm/alexandria-ee/. From a checkout:

git clone <your-fork>/alexandria-ee
cd alexandria-ee

2. Configure values​

Create values-prod.yaml with the minimum required fields:

image:
  repository: us-central1-docker.pkg.dev/your-project/alexandria/ee-api-k8s
  tag: v1.0.0

license:
  key: "<YOUR_LICENSE_KEY>"

database:
  dsn: "postgres://alex:CHANGE_ME@pg.internal:5432/alexandria?sslmode=require"

auth:
  jwtSecret: "<32-byte-hex>"           # openssl rand -hex 32
  adminUsername: "admin"
  adminPassword: "<initial-password>"  # rotate after first login

ingress:
  enabled: true
  hosts:
    - alexandria.example.com

For everything else (federation, SCIM, Cilium, KEDA, observability) see Helm on Kubernetes.

3. Install​

helm upgrade --install alexandria-ee k8s/helm/alexandria-ee/ \
  --namespace alexandria --create-namespace \
  -f values-prod.yaml

Watch the rollout:

kubectl rollout status deployment/alexandria-ee -n alexandria
kubectl get pods -n alexandria

4. Verify​

# Port-forward locally for the first check
kubectl port-forward -n alexandria svc/alexandria-ee 8080:80 &

# Liveness
curl -fsS http://localhost:8080/health
# {"status":"ok"}

# Readiness (DB + orchestrator socket)
curl -fsS http://localhost:8080/ready
# {"status":"ok","db":"ok","orchestrator":"ok"}

# License state
curl -fsS http://localhost:8080/admin/license \
  -H "Authorization: Bearer <admin-token>"

5. First login​

Acquire an admin access token:

curl -fsS -X POST http://localhost:8080/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<initial-password>"}'

Save access_token from the response. See API → Auth for the full flow including refresh and WebAuthn.

Next steps​