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

Cookie Security

Stategraph derives cookie security from STATEGRAPH_UI_BASE:

  • https:// URLs → cookies are set with the Secure flag (recommended for production)
  • http:// URLs → cookies are set without the Secure flag (suitable for development or internal networks)

For example, setting stategraph.ui.base=http://myserver:8080 allows authentication over plain HTTP.

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:

Parameter Description Default
stategraph.image.tag Stategraph version latest
stategraph.replicaCount Number of replicas 1
stategraph.ui.base Public URL http://localhost:8080
postgresql.enabled Use bundled PostgreSQL true
postgresql.auth.existingSecret Use external secret ""
postgresql.persistence.size Database storage 10Gi
ingress.enabled Enable ingress false

See the full chart documentation for all options.

Health Checks

Stategraph provides two health check endpoints for Kubernetes probes:

Endpoint Purpose Use For
/health/live Returns 200 as long as nginx is running livenessProbe
/health/ready Returns 200 when the backend is ready to serve requests readinessProbe

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.

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