> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Step-by-step installation instructions for CrewAI Platform via Helm and Replicated

## Overview

CrewAI Platform is distributed as a Helm chart via OCI registry through the Replicated platform. This guide covers installation, preflight validation, and post-installation configuration.

> [!NOTE]
>
> Before running `helm install`, complete the [Pre-Install Checklist](https://enterprise-docs.crewai.com/installation/pre-install-checklist.md) — it covers database creation, auth provider redirect URIs, IAM setup, and known chart gotchas that cause silent failures.

## Step 1: Registry Authentication

Access your registry credentials via the CrewAI enterprise customer portal at `https://enterprise.crewai.com/crewai`.

> [!NOTE]
>
> Replace `customer@company.com` with your actual customer email and `[YOUR_SECRET_TOKEN]` with the token provided in the customer portal.

```bash theme={null}
# Export your authentication token
export AUTH_TOKEN=[YOUR_SECRET_TOKEN]

# Log in to the Replicated registry
helm registry login registry.crewai.com \
  --username customer@company.com \
  --password $AUTH_TOKEN
```

## Step 2: Install Required Plugins

Install the preflight and support-bundle kubectl plugins for cluster validation and diagnostics:

```bash theme={null}
# Install Krew plugin manager
curl https://krew.sh | bash

# Insall preflight and support-bundle plugins
kubectl krew install preflight support-bundle

# Verify installation
kubectl preflight --version
kubectl support-bundle --version
```

## Step 2.5: Provision Infrastructure (Terraform Option)

If you want to provision cloud infrastructure before chart installation, use one of these Terraform feature guides:

* [Terraform Infrastructure on AWS](https://enterprise-docs.crewai.com/features/terraform-aws.md)
* [Terraform Infrastructure on GCP](https://enterprise-docs.crewai.com/features/terraform-gcp.md)
* [Terraform Infrastructure on Azure](https://enterprise-docs.crewai.com/features/terraform-azure.md)

> [!WARNING]
>
> Request the Terraform files from the CrewAI Factory Engineering team before starting Terraform provisioning.

Each guide covers infrastructure provisioning and how to map Terraform outputs into your Helm values.

## Step 3: Create Configuration File

Create a `my-values.yaml` file with your deployment configuration. See the [Configuration Guide](https://enterprise-docs.crewai.com/configuration/configuration.md) for detailed examples.

> [!NOTE]
>
> **Pre-install checklist for Microsoft Entra ID users:** If you are using Microsoft Entra ID as your authentication provider, configure the redirect URI in your Azure App Registration to `https://<your-domain>/auth/entra_id/callback` before running `helm install`. Authentication will fail at login if this is missing or incorrect. See the [Microsoft Entra ID Guide](https://enterprise-docs.crewai.com/features/entra-id.md) for step-by-step instructions.

> [!WARNING]
>
> **External PostgreSQL users:** If you set `postgres.enabled: false`, you must manually create the Wharf database before running `helm install`. Wharf is enabled by default (`wharf.enabled: true`).
>
> ```sql theme={null}
> -- AWS RDS / Azure Database for PostgreSQL
> CREATE DATABASE wharf;
> GRANT ALL PRIVILEGES ON DATABASE wharf TO your_db_user;
> ```
>
> ```bash theme={null}
> # GCP Cloud SQL
> gcloud sql databases create wharf --instance=<YOUR_INSTANCE_NAME>
> ```
>
> See [Wharf Configuration](https://enterprise-docs.crewai.com/reference/chart-values/wharf.md) for details.

> [!WARNING]
>
> **GCP Cloud SQL IAM authentication users** must also run schema-level SQL grants (not just `GRANT ALL PRIVILEGES ON DATABASE`). The `GRANT ALL PRIVILEGES ON DATABASE` command alone is insufficient for Cloud SQL IAM auth users — additional schema, table, and sequence grants are required before `helm install`. See the GCP Integration Guide for the complete SQL.

***

**Direct Helm Install Users**

> [!WARNING]
>
> **Direct Helm install users (non-KOTS/non-Replicated):** You must manually set `secrets.UV_DEFAULT_INDEX`. In Replicated KOTS deployments this value is auto-generated from your license credentials. For direct OCI Helm installs — including Helm CLI installs and ArgoCD — no Replicated license context is available, so `UV_DEFAULT_INDEX` is not set automatically.
>
> Without it, crew container builds fail because the Python package registry at `pypi.crewaifactory.com` requires credentials. To obtain your credentials, log in to the customer portal at `https://enterprise.crewai.com/crewai` and navigate to your license details.
>
> ```yaml theme={null}
> secrets:
>   UV_DEFAULT_INDEX: "https://<customer-id>:<registry-password>@pypi.crewaifactory.com/simple/"
> ```

> [!NOTE]
>
> Crew automation deployments require a writable container registry. See [Container Image Registry Requirements](https://enterprise-docs.crewai.com/installation/requirements.md#container-image-registry-requirements).

> [!WARNING]
>
> The following features CANNOT be pre-configured in `values.yaml` — they require post-installation steps and will be silently ignored if added as Helm values:
>
> * **Admin users and org ownership** — there is no `adminUsers` Helm key. Use `kubectl exec` commands after install. See the [Post-Installation Guide](https://enterprise-docs.crewai.com/installation/post-installation.md).
> * **Studio V2** — there is no `studioV2.enabled` Helm key. Studio V2 requires interactive UI setup plus `kubectl exec` commands. See the [Post-Installation Guide](https://enterprise-docs.crewai.com/installation/post-installation.md) and Studio V2 Setup Guide.

> [!NOTE]
>
> Do not set `image.tag: latest` in production. Using `latest` means upgrades are non-deterministic and the exact version running cannot be verified. Always specify an explicit version tag matching your Helm chart version. The chart's `values.yaml` explicitly warns against `latest`. Check the Release History at [https://enterprise.crewai.com/crewai/release-history](https://enterprise.crewai.com/crewai/release-history) for available image tags.

**Minimum Production Configuration:**

```yaml my-values.yaml lines theme={null}
postgres:
  enabled: false  # Use external database

envVars:
  APPLICATION_HOST: "crewai.company.com"
  DB_HOST: "crewai-prod.cluster-xyz.us-west-2.rds.amazonaws.com"
  DB_PORT: "5432"
  DB_USER: "crewai"
  POSTGRES_DB: "crewai_plus_production"
  POSTGRES_CABLE_DB: "crewai_plus_cable_production"

  STORAGE_SERVICE: "amazon"
  AWS_REGION: "us-west-2"
  AWS_BUCKET: "crewai-prod-storage"
  CREW_IMAGE_REGISTRY_OVERRIDE: "123456789012.dkr.ecr.us-west-2.amazonaws.com"

  AUTH_PROVIDER: "entra_id"
  # Client ID and Tenant ID are non-sensitive identifiers — must be in envVars, not secrets
  ENTRA_ID_CLIENT_ID: "your-client-id"
  ENTRA_ID_TENANT_ID: "your-tenant-id"

secrets:
  DB_PASSWORD: "your-db-password"
  AWS_ACCESS_KEY_ID: "your-aws-key"
  AWS_SECRET_ACCESS_KEY: "your-aws-secret"
  ENTRA_ID_CLIENT_SECRET: "your-client-secret"

web:
  replicaCount: 2
  ingress:
    enabled: true
    className: nginx
    host: "crewai.company.com"
    nginx:
      tls:
        enabled: true
        secretName: "crewai-tls"
```

> [!WARNING]
>
> Never commit secrets to version control. Store `my-values.yaml` securely and use CI/CD secret management or external secret stores for production.

## Step 3.5: Validate Your Values File

Before running preflight checks, validate that your values file is syntactically correct and free of duplicate keys:

> [!WARNING]
>
> **Run yamllint before every helm install or helm upgrade.** Helm silently accepts YAML files with duplicate top-level keys (e.g., two `envVars:` blocks or two `image:` blocks) and keeps only the last occurrence — the first block is dropped with no error or warning. This means database credentials, auth configuration, or image tags can vanish silently.
>
> The `helm template` dry-run and `helm lint` commands do NOT catch duplicate keys.
>
> ```bash theme={null}
> # Install yamllint (once)
> pip install yamllint
>
> # Check your values file before EVERY install or upgrade
> yamllint my-values.yaml
> ```
>
> A common mistake is writing `envVars:` twice — once for database/auth config and once for GitHub App or other feature config. Merge all `envVars:` keys into a single block.

## Step 4: Run Preflight Checks

Validate your Kubernetes cluster meets all requirements before installation:

```bash theme={null}
# Run preflight checks against your cluster
helm template oci://registry.crewai.com/crewai/stable/crewai-platform \
  --values my-values.yaml \
  | kubectl preflight -
```

> [!NOTE]
>
> Preflight checks validate cluster requirements and run environment-specific probes from inside the cluster to verify:
>
> * Kubernetes version (1.32.0+ required), cluster resources (14Gi memory, 4 CPU cores minimum), and storage classes
> * **External PostgreSQL**: Connectivity, version 15+, and database existence
> * **S3-Compatible Storage**: Write/delete permissions to the configured bucket
> * **Crew Image Registry**: Push permission (or reachability if using credential helpers like ECR/GCR)
> * **CrewAI Hosted Services**: Egress to images.crewai.com and pypi.crewaifactory.com (online installs)
> * **APPLICATION\_HOST**: DNS resolution (advisory)
>
> Address any failures before proceeding with installation. For probe failures, check the support bundle pod logs for specific error messages.
>
> CrewAI Platform supports AMD64 (x86\_64) Kubernetes worker nodes. ARM64 (aarch64) worker nodes are not currently supported. See the [Requirements Guide](https://enterprise-docs.crewai.com/installation/requirements.md#architecture-support) for details.

### Common Preflight Issues

**Kubernetes Version:**

* Kubernetes 1.32.0 or later is required. Upgrade your cluster if the version check fails.

**Insufficient Cluster Resources:**

* Minimum requirements: 14Gi memory, 4 CPU cores (20Gi+ memory and 8+ cores recommended)
* Review node resources: `kubectl top nodes`
* Scale cluster if needed before installation

**Missing Default Storage Class:**
Only required if using internal PostgreSQL.

```bash theme={null}
# Set gp2 (EKS) as default storage class
kubectl patch storageclass gp2 -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

# Or for GKE standard storage
kubectl patch storageclass standard -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
```

**External Database Probe Failure:**
If the external PostgreSQL probe fails, verify:

* Database host is reachable from cluster pods on the configured port
* PostgreSQL version is 15 or later
* All required databases exist (check default names: `crewai_plus_production`, `crewai_plus_cable_production`, `crewai_plus_oauth_production`, `wharf`)
* Database credentials are correct in your values file

**Object Storage Probe Failure:**
If the S3-compatible storage probe fails, verify:

* Bucket exists and is accessible from the cluster
* Credentials have write and delete permissions
* Endpoint URL is correct (if using non-AWS S3)

**Registry Push Probe Failure:**
If the crew image registry probe fails, verify:

* Registry hostname is reachable from cluster pods
* Credentials have push permission to the configured repository
* For ECR/ACR/GAR: Ensure credentials or credential helpers are properly configured

**CrewAI Services Egress Failure:**
If the CrewAI hosted services probe fails (online installs only):

* Verify firewall/proxy allows HTTPS egress to `images.crewai.com` and `pypi.crewaifactory.com`
* Check cluster DNS can resolve these hostnames
* Review network policies if using restricted egress

## Step 5: Install the Chart

```bash theme={null}
# Install with your configuration
helm install crewai-platform \
  oci://registry.crewai.com/crewai/stable/crewai-platform \
  --values my-values.yaml

# Monitor installation progress
kubectl get pods -w
```

After installation completes, Helm displays important information including:

* Chart version and app image tag
* Link to complete documentation
* Configuration warnings (if any)

> [!NOTE]
>
> If you see a warning about `RAILS_MASTER_KEY` in the installation output, remove this configuration from your values file. The chart automatically manages this key and manual configuration is not needed.

### Verify Installation

```bash theme={null}
# Check all pods are running
kubectl get pods

# Check services
kubectl get svc

# View installation logs
kubectl logs -l app.kubernetes.io/name=crewai-platform --tail=50
```

## Step 6: Complete Post-Installation Setup

After successful installation, complete the required post-installation configuration steps.

See the [Post-Installation Guide](https://enterprise-docs.crewai.com/installation/post-installation.md) for detailed instructions.

**MANDATORY — required before any user can log in:**

* Initialize the internal organization (`studio:install_internal_organization`)
* Set up default permissions (`factory:setup_permissions_defaults`)
* Grant Admin Panel access (`factory:grant_admin`)
* Add an owner to the organization (`factory:add_owner`)

> [!NOTE]
>
> Admin user setup cannot be expressed in values.yaml — it requires `kubectl exec` commands after the platform is running.

**OPTIONAL — can be performed after the platform is accessible:**

* Enable Studio V2 features (requires interactive UI setup — cannot be pre-configured in values.yaml)
* Enable Multi-Organization Namespace Isolation
* Accessing the application via port forwarding, ingress, or LoadBalancer

## Troubleshooting Installation

### Pods Not Starting

```bash theme={null}
# Check pod status and events
kubectl describe pod <POD_NAME>

# View pod logs
kubectl logs <POD_NAME>

# Check for image pull issues
kubectl get events --sort-by='.lastTimestamp'
```

### Generate Support Bundle

For comprehensive diagnostics, you can generate a support bundle that collects logs, resource status, and configuration information.

#### Install the support-bundle Plugin

```bash theme={null}
# Using Krew (recommended)
kubectl krew install support-bundle
```

#### Generate the Support Bundle

```bash theme={null}
# Automatically detect support bundle specs from cluster
kubectl support-bundle --load-cluster-specs
```

The support bundle will be saved as a `.tar.gz` file that can be shared with CrewAI support for troubleshooting.

## Next Steps

* [Post-Installation](https://enterprise-docs.crewai.com/installation/post-installation.md) - Complete setup and access the application
* [Configuration Guide](https://enterprise-docs.crewai.com/configuration/configuration.md) - Detailed production configuration patterns
* [Troubleshooting](https://enterprise-docs.crewai.com/troubleshooting.md) - Common issues and solutions

## Additional Resources

* **Customer Portal**: `https://enterprise.crewai.com/crewai`
* **Release History**: `https://enterprise.crewai.com/crewai/release-history`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.