Skip to main content

Installation Guide

Deploy Align on your Kubernetes cluster.

Getting the Helm Chart​

Align publishes Helm charts to our ECR registry as OCI artifacts:

# Login to Align's ECR (credentials provided during onboarding)
aws ecr get-login-password --region eu-west-2 | \
  helm registry login --username AWS --password-stdin \
  869633161172.dkr.ecr.eu-west-2.amazonaws.com

# Pull the chart
helm pull oci://869633161172.dkr.ecr.eu-west-2.amazonaws.com/align/charts/align \
  --version 0.8.0

# Or install directly
helm install align \
  oci://869633161172.dkr.ecr.eu-west-2.amazonaws.com/align/charts/align \
  --version 0.8.0 \
  --namespace align \
  --values values.yaml

For production deployments, we recommend mirroring all artifacts to your own registry. This provides:

  • Reliability — No dependency on Align's infrastructure
  • Security — Full control over what runs in your cluster
  • Compliance — Artifacts scanned by your security tools
  • Air-gap support — Works in isolated environments

Step 1: Mirror the Helm Chart​

# Login to Align's ECR
aws ecr get-login-password --region eu-west-2 | \
  helm registry login --username AWS --password-stdin \
  869633161172.dkr.ecr.eu-west-2.amazonaws.com

# Pull the chart
helm pull oci://869633161172.dkr.ecr.eu-west-2.amazonaws.com/align/charts/align \
  --version 1.0.0

# Push to your registry
helm push align-1.0.0.tgz oci://your-registry.example.com/align/charts

Step 2: Mirror Docker Images​

All images for a release use the same version tag:

VERSION="v1.0.0"
SOURCE_REGISTRY="869633161172.dkr.ecr.eu-west-2.amazonaws.com/align"
TARGET_REGISTRY="your-registry.example.com/align"

IMAGES=(
  "gateway"
  "brain"
  "ui"
  "migrations"
  "connector-slack"
  "connector-github"
  "connector-jira"
  "connector-teams"
)

for image in "${IMAGES[@]}"; do
  docker pull "${SOURCE_REGISTRY}/${image}:${VERSION}"
  docker tag "${SOURCE_REGISTRY}/${image}:${VERSION}" "${TARGET_REGISTRY}/${image}:${VERSION}"
  docker push "${TARGET_REGISTRY}/${image}:${VERSION}"
done

Step 3: Configure Helm to Use Your Registry​

# values.yaml
global:
  imageRegistry: your-registry.example.com/align
  # Optional: if your registry requires auth
  imagePullSecrets:
    - name: your-registry-secret

Automating Mirror Updates​

Create a CI job to mirror new releases:

# .github/workflows/mirror-align.yaml (example)
name: Mirror Align Release
on:
  schedule:
    - cron: '0 6 * * *'  # Daily at 6 AM
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to mirror (e.g., 1.0.0)'
        required: true

jobs:
  mirror:
    runs-on: ubuntu-latest
    steps:
      - name: Mirror Align artifacts
        run: |
          # Your mirroring script here

Option C: Direct from GitHub (Development)​

For testing or development:

git clone https://github.com/aligndottech/align-stack.git
helm install align ./align-stack/charts/align \
  --namespace align \
  --values values.yaml

Prerequisites​

Before you begin, ensure you have:

  • Kubernetes 1.25+ cluster
  • Helm 3.10+
  • kubectl configured for your cluster
  • PostgreSQL 15+ database (RDS, Cloud SQL, or self-hosted)
  • Ingress controller (Traefik, nginx, etc.)
  • (Recommended) cert-manager for TLS

Step 1: Create Namespace​

kubectl create namespace align

Step 2: Configure Database​

Create a secret with your database credentials:

kubectl create secret generic align-database \
  --namespace align \
  --from-literal=url="postgresql://user:password@host:5432/align" \
  --from-literal=host="your-db-host.example.com" \
  --from-literal=port="5432" \
  --from-literal=username="align" \
  --from-literal=password="your-secure-password"

Option B: Deploy PostgreSQL in Cluster​

For development/testing, you can deploy PostgreSQL alongside Align:

# values.yaml
postgresql:
  enabled: true
  auth:
    database: align
    username: align
    password: your-secure-password
warning

In-cluster PostgreSQL is not recommended for production. Use a managed database service like RDS.

Step 3: Configure Secrets​

Align requires several secrets for operation. See Secrets Management for detailed options.

Minimal Secrets​

At minimum, create internal secrets:

kubectl create secret generic align-internal \
  --namespace align \
  --from-literal=jwt-secret="$(openssl rand -base64 32)" \
  --from-literal=cookie-secret="$(openssl rand -base64 32)" \
  --from-literal=encryption-key="$(openssl rand -base64 32)" \
  --from-literal=service-auth-token="$(openssl rand -base64 32)"

LLM Secrets (Required for AI features)​

kubectl create secret generic align-llm \
  --namespace align \
  --from-literal=openai-api-key="sk-..." \
  # OR
  --from-literal=anthropic-api-key="sk-ant-..."

Or see LLM Setup for self-hosted models.

Step 4: Create Values File​

Create a values.yaml file for your deployment:

# values.yaml
global:
  environment: production

# Database
database:
  secretName: align-database

# Gateway
gateway:
  replicaCount: 2
  frontendUrl: "https://app.yourdomain.com"
  ingress:
    enabled: true
    className: "nginx"  # or "traefik"
    hosts:
      - host: api.yourdomain.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: api-tls
        hosts:
          - api.yourdomain.com

# UI
ui:
  replicaCount: 2
  ingress:
    enabled: true
    className: "nginx"
    hosts:
      - host: app.yourdomain.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: app-tls
        hosts:
          - app.yourdomain.com

# Brain (AI Service)
brain:
  replicaCount: 2

# Connectors - disable unused ones
connectors:
  slack:
    enabled: true
  teams:
    enabled: true
  jira:
    enabled: true
  github:
    enabled: true
  linear:
    enabled: false  # Enable if needed

# Secrets
secrets:
  create: false  # Use pre-created secrets

See Configuration Reference for all options.

Step 5: Install Align​

helm install align \
  oci://your-registry.example.com/align/charts/align \
  --version 1.0.0 \
  --namespace align \
  --values values.yaml

From Align's Registry (Direct)​

helm install align \
  oci://869633161172.dkr.ecr.eu-west-2.amazonaws.com/align/charts/align \
  --version 1.0.0 \
  --namespace align \
  --values values.yaml

Step 6: Verify Installation​

# Check pods are running
kubectl get pods -n align

# Expected output:
# NAME                              READY   STATUS    RESTARTS   AGE
# align-gateway-xxx                 1/1     Running   0          2m
# align-brain-xxx                   1/1     Running   0          2m
# align-ui-xxx                      1/1     Running   0          2m
# align-connector-slack-xxx         1/1     Running   0          2m
# ...

# Check services
kubectl get svc -n align

# Check ingress
kubectl get ingress -n align

Step 7: Run Migrations​

Migrations run automatically as a Helm pre-install hook. Verify they completed:

kubectl get jobs -n align

# Should show:
# NAME                    COMPLETIONS   DURATION   AGE
# align-migrations        1/1           30s        5m

Step 8: Access Align​

  1. Ensure DNS is configured for your domains
  2. Navigate to https://app.yourdomain.com
  3. Sign in or create your first user

Troubleshooting​

Pods not starting​

# Check pod status
kubectl describe pod -n align <pod-name>

# Check logs
kubectl logs -n align <pod-name>

Database connection issues​

# Verify secret exists
kubectl get secret align-database -n align

# Test connection from a pod
kubectl run -it --rm debug --image=postgres:15 \
  --restart=Never -n align -- \
  psql "postgresql://user:pass@host:5432/align"

Ingress not working​

# Check ingress status
kubectl describe ingress -n align

# Verify TLS secret exists
kubectl get secret api-tls -n align

Next Steps​