Installation Guide

Deploy Align on your Kubernetes cluster.

Getting the Helm Chart

Option A: OCI Registry (Recommended)

Align publishes Helm charts to our OCI registry. Contact us during onboarding for registry credentials.

# Pull the chart
helm pull oci://registry.align.tech/charts/align --version 1.0.0

# Or install directly
helm install align \
  oci://registry.align.tech/charts/align \
  --version 1.0.0 \
  --namespace align \
  --values values.yaml

note

For production deployments, we recommend mirroring artifacts to your own registry (Option B below).

Option B: Mirror to Your Registry (Recommended for Production)

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

# Pull the chart from Align's registry
helm pull oci://registry.align.tech/charts/align --version 1.0.0

# Push to your registry (choose your cloud provider)
helm push align-1.0.0.tgz oci://your-registry/align/charts

Step 2: Mirror Docker Images

All images for a release use the same version tag:

VERSION="v1.0.0"
SOURCE_REGISTRY="registry.align.tech/align"

# Set your target registry based on your cloud:
# AWS ECR:     TARGET_REGISTRY="123456789.dkr.ecr.us-east-1.amazonaws.com/align"
# Azure ACR:   TARGET_REGISTRY="myregistry.azurecr.io/align"
# GCP:         TARGET_REGISTRY="us-docker.pkg.dev/my-project/align"
# Docker Hub:  TARGET_REGISTRY="docker.io/myorg/align"
TARGET_REGISTRY="your-registry/align"

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

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:
  # Your container registry (examples for different clouds)
  # AWS ECR:     imageRegistry: "123456789.dkr.ecr.us-east-1.amazonaws.com/align"
  # Azure ACR:   imageRegistry: "myregistry.azurecr.io/align"
  # GCP:         imageRegistry: "us-docker.pkg.dev/my-project/align"
  imageRegistry: your-registry/align

  # Registry authentication (if required)
  imagePullSecrets:
    - name: registry-credentials

Creating Registry Pull Secrets

AWS ECR

# Create secret with ECR credentials
kubectl create secret docker-registry ecr-credentials \
  --namespace align \
  --docker-server=123456789.dkr.ecr.us-east-1.amazonaws.com \
  --docker-username=AWS \
  --docker-password=$(aws ecr get-login-password --region us-east-1)

Or use ECR credential helper with IRSA.

Azure ACR

# Create secret with ACR credentials
kubectl create secret docker-registry acr-credentials \
  --namespace align \
  --docker-server=myregistry.azurecr.io \
  --docker-username=<service-principal-id> \
  --docker-password=<service-principal-password>

Or use ACR with AKS managed identity.

Google Artifact Registry

# Create secret with GCP credentials
kubectl create secret docker-registry gcr-credentials \
  --namespace align \
  --docker-server=us-docker.pkg.dev \
  --docker-username=_json_key \
  --docker-password="$(cat service-account-key.json)"

Or use Workload Identity.

Option C: From Source (Licensed Customers)

For licensed customers with repository access:

git clone <your-align-repo-url>
helm install align ./align-stack/charts/align \
  --namespace align \
  --values values.yaml

Contact support@align.tech for repository access.

Prerequisites

Before you begin, ensure you have:

Kubernetes 1.25+ cluster (EKS, AKS, GKE, or self-managed)
Helm 3.10+
kubectl configured for your cluster
PostgreSQL 15+ database with pgvector extension:
- AWS: RDS PostgreSQL or Aurora PostgreSQL
- Azure: Azure Database for PostgreSQL Flexible Server
- GCP: Cloud SQL for PostgreSQL
- Self-hosted: PostgreSQL with pgvector installed
Ingress controller (Traefik, nginx, or cloud-native like ALB/Application Gateway)
(Recommended) cert-manager for TLS

Step 1: Create Namespace

kubectl create namespace align

Step 2: Configure Database

Option A: Use Existing PostgreSQL (Recommended)

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:

AWS: RDS PostgreSQL or Aurora PostgreSQL
Azure: Azure Database for PostgreSQL Flexible Server
GCP: Cloud SQL for PostgreSQL

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
  align:
    enabled: false  # Enable for AI assistant integration (Claude, Cursor)

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

See Configuration Reference for all options.

Step 5: Install Align

From Your Mirrored Registry (Recommended)

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

From Align's Registry (Direct)

helm install align \
  oci://registry.align.tech/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

Ensure DNS is configured for your domains
Navigate to https://app.yourdomain.com
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

Configure OAuth Apps for Slack, Teams, etc.
Set up LLM for decision synthesis
Configure secrets properly for production

Getting the Helm Chart​

Option A: OCI Registry (Recommended)​

Option B: Mirror to Your Registry (Recommended for Production)​

Step 1: Mirror the Helm Chart​

Step 2: Mirror Docker Images​

Step 3: Configure Helm to Use Your Registry​

Creating Registry Pull Secrets​

Option C: From Source (Licensed Customers)​

Prerequisites​

Step 1: Create Namespace​

Step 2: Configure Database​

Option A: Use Existing PostgreSQL (Recommended)​

Option B: Deploy PostgreSQL in Cluster​

Step 3: Configure Secrets​

Minimal Secrets​

LLM Secrets (Required for AI features)​

Step 4: Create Values File​

Step 5: Install Align​

From Your Mirrored Registry (Recommended)​

From Align's Registry (Direct)​

Step 6: Verify Installation​

Step 7: Run Migrations​

Step 8: Access Align​

Troubleshooting​

Pods not starting​

Database connection issues​

Ingress not working​

Next Steps​