Kubernetes

Deploy Stategraph on Kubernetes using the official Helm chart.

Prerequisites

• Kubernetes 1.19+
• Helm 3.0+
• kubectl configured for your cluster
• Ingress controller (optional, for external access)

Quick Start

1. Add the Helm repository:

helm repo add stategraph https://stategraph.github.io/helm-charts
helm repo update

2. Install Stategraph:

helm install stategraph stategraph/stategraph \
  --namespace stategraph \
  --create-namespace

3. Access Stategraph:

For local testing:

kubectl port-forward -n stategraph svc/stategraph 8080:80

Then access at http://localhost:8080

⚠️ Important - Secure Cookie Configuration

Stategraph uses secure cookies. For proper authentication:

• Local/development: Use http://localhost:8080 (browsers allow secure cookies on localhost)
• Production: Use HTTPS like https://stategraph.example.com
• DO NOT use custom hostnames over HTTP (e.g., http://myserver:8080) - authentication will fail

For remote clusters with port-forward, use SSH tunnel: ssh -L 8080:localhost:8080 your-server

Production Installation

For production with HTTPS and ingress:

helm install stategraph stategraph/stategraph \
  --namespace stategraph \
  --create-namespace \
  --set stategraph.ui.base="https://stategraph.example.com" \
  --set stategraph.ui.oauthRedirectBase="https://stategraph.example.com" \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host="stategraph.example.com" \
  --set ingress.hosts[0].paths[0].path="/" \
  --set ingress.hosts[0].paths[0].pathType="Prefix" \
  --set ingress.tls[0].secretName="stategraph-tls" \
  --set ingress.tls[0].hosts[0]="stategraph.example.com" \
  --set ingress.annotations."cert-manager\.io/cluster-issuer"="letsencrypt-prod"

Configuration Options

View all available configuration options:

helm show values stategraph/stategraph

Common configurations:

See the full chart documentation for all options.

Health Checks

Stategraph provides two health check endpoints for Kubernetes probes:

The Helm chart configures these probes automatically. If you need to customize them:

# values.yaml
livenessProbe:
  httpGet:
    path: /health/live
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health/ready
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 10
  failureThreshold: 10

During startup, database migrations run before the backend starts. The liveness probe passes immediately (nginx is up), while the readiness probe will fail until migrations complete and the backend is ready.

For more details, see the Health Checks reference.

Upgrading

helm repo update
helm upgrade stategraph stategraph/stategraph -n stategraph

Uninstalling

helm uninstall stategraph -n stategraph
kubectl delete namespace stategraph

Using External PostgreSQL

To use an existing PostgreSQL database instead of the bundled one:

helm install stategraph stategraph/stategraph \
  --namespace stategraph \
  --create-namespace \
  --set postgresql.enabled=false \
  --set postgresql.host="your-postgres-host.example.com" \
  --set postgresql.port=5432 \
  --set postgresql.auth.username="stategraph" \
  --set postgresql.auth.existingSecret="external-db-secret"

Create the secret with your database password:

kubectl create secret generic external-db-secret \
  --from-literal=db-password='your-password' \
  -n stategraph

Authentication

To enable OAuth authentication, configure the OAuth settings during installation:

helm install stategraph stategraph/stategraph \
  --namespace stategraph \
  --create-namespace \
  --set stategraph.oauth.enabled=true \
  --set stategraph.oauth.type="google" \
  --set stategraph.oauth.clientId="your-client-id" \
  --set stategraph.oauth.clientSecret="your-client-secret"

See the Authentication guide for detailed OAuth setup instructions.

Create an API Key

Terraform authenticates to Stategraph using an API key. Without one, terraform init will fail with a 401 Unauthorized error.

1. Log in to the UI (via kubectl port-forward or your ingress URL)
2. Go to Settings > API Keys
3. Click Create API Key and copy the token
4. Set the environment variables Terraform expects:

export TF_HTTP_USERNAME="session"
export TF_HTTP_PASSWORD="<your-api-key>"

You're now ready to configure Terraform to store state in Stategraph.

Troubleshooting

# Check pod status
kubectl get pods -n stategraph

# View logs
kubectl logs -n stategraph -l app.kubernetes.io/name=stategraph

# Check events
kubectl get events -n stategraph --sort-by='.lastTimestamp'

Next Steps

• Configure your first Terraform state — connect Terraform using your API key
• Set up OAuth authentication