Kubernetes Installation

This guide walks you through deploying Activepieces on Kubernetes using the official Helm chart.

Prerequisites

Kubernetes cluster (v1.19+)
Helm 3.x installed
kubectl configured to access your cluster

Using External PostgreSQL and Redis

The Helm chart supports using external PostgreSQL and Redis services instead of deploying the Bitnami subcharts.

Using External PostgreSQL

To use an external PostgreSQL instance:

postgresql:
  enabled: false  # Disable Bitnami PostgreSQL subchart
  host: "your-postgres-host.example.com"
  port: 5432
  useSSL: true  # Enable SSL if required
  auth:
    database: "activepieces"
    username: "postgres"
    password: "your-password"
    # Or use external secret reference:
    # externalSecret:
    #   name: "postgresql-credentials"
    #   key: "password"

Alternatively, you can use a connection URL:

postgresql:
  enabled: false
  url: "postgresql://user:password@host:5432/database?sslmode=require"

Using External Redis

To use an external Redis instance:

redis:
  enabled: false  # Disable Bitnami Redis subchart
  host: "your-redis-host.example.com"
  port: 6379
  useSSL: false  # Enable SSL if required
  auth:
    enabled: true
    password: "your-password"
    # Or use external secret reference:
    # externalSecret:
    #   name: "redis-credentials"
    #   key: "password"

Alternatively, you can use a connection URL:

redis:
  enabled: false
  url: "redis://:password@host:6379/0"

External Secret References

For better security, you can reference passwords from existing Kubernetes secrets (useful with External Secrets Operator or Sealed Secrets):

postgresql:
  enabled: false
  host: "your-postgres-host.example.com"
  auth:
    externalSecret:
      name: "postgresql-credentials"
      key: "password"

redis:
  enabled: false
  host: "your-redis-host.example.com"
  auth:
    enabled: true
    externalSecret:
      name: "redis-credentials"
      key: "password"

Quick Start

1. Clone the Repository

git clone https://github.com/activepieces/activepieces.git
cd activepieces

2. Install Dependencies

helm dependency update

3. Create a Values File

Create a my-values.yaml file with your configuration. You can use the example values file as a reference. The Helm chart has sensible defaults for required values while leaving the optional ones empty, but you should customize these core values for production. Include these so you can activate a license key later:

activepiecesConfig:
  AP_EDITION: "ee"
  AP_EXECUTION_MODE: "SANDBOX_CODE_ONLY"

Set both, and set each variable in one place only. activepiecesConfig writes plain values into the pod, while activepiecesEnvVariables pulls the same names from Kubernetes secrets you create yourself and renders after it, so a secret that holds the key wins. The chart lists AP_EDITION and AP_EXECUTION_MODE under activepieces-config-secrets by default, so either remove them from there or set them in that secret instead of here.AP_EDITION=ee with the default execution mode is rejected at startup and the app will not boot.

4. Install Activepieces

helm install activepieces deploy/activepieces-helm -f my-values.yaml

5. Verify Installation

# Check deployment status
kubectl get pods
kubectl get services

Production Checklist

Set frontendUrl to your actual domain
Set strong passwords for PostgreSQL and Redis (or keep auto-generated)
Configure proper ingress with TLS
Set appropriate resource limits
Configure persistent storage
Choose appropriate execution mode for your security requirements
Review environment variables for advanced configuration
Consider using a separate workers setup for better availability and security

Upgrading

# Update dependencies
helm dependency update

# Upgrade release
helm upgrade activepieces deploy/activepieces-helm -f my-values.yaml

# Check upgrade status
kubectl rollout status deployment/activepieces

Troubleshooting

Common Issues

Pod won’t start: Check logs with kubectl logs deployment/activepieces
Database connection: Verify PostgreSQL credentials and connectivity
Frontend URL: Ensure frontendUrl is accessible from external sources
Webhooks not working: Check ingress configuration and DNS resolution

Useful Commands

# View logs
kubectl logs deployment/activepieces -f

# Port forward for testing
kubectl port-forward svc/activepieces 4200:80 --namespace default

# Get all resources
kubectl get all --namespace default

Environment Variables

For a complete list of configuration options, see the Environment Variables documentation. Most environment variables can be configured through the Helm values file, either as plain values under activepiecesConfig or injected from your own secrets under activepiecesEnvVariables.

Execution Modes

Understanding execution modes is crucial for security and performance. See the Sandboxing guide to choose the right mode for your deployment.

Uninstalling

helm uninstall activepieces

# Clean up persistent volumes (optional)
kubectl delete pvc -l app.kubernetes.io/instance=activepieces

Install Activepieces

Self hosting

Troubleshooting

Reference

Guarantees

Architecture

Kubernetes Installation

Prerequisites

Using External PostgreSQL and Redis

Using External PostgreSQL

Using External Redis

External Secret References

Quick Start

1. Clone the Repository

2. Install Dependencies

3. Create a Values File

4. Install Activepieces

5. Verify Installation

Production Checklist

Upgrading

Troubleshooting

Common Issues

Useful Commands

Environment Variables

Execution Modes

Uninstalling

​Prerequisites

​Using External PostgreSQL and Redis

​Using External PostgreSQL

​Using External Redis

​External Secret References

​Quick Start

​1. Clone the Repository

​2. Install Dependencies

​3. Create a Values File

​4. Install Activepieces

​5. Verify Installation

​Production Checklist

​Upgrading

​Troubleshooting

​Common Issues

​Useful Commands

​Environment Variables

​Execution Modes

​Uninstalling

Prerequisites

Using External PostgreSQL and Redis

Using External PostgreSQL

Using External Redis

External Secret References

Quick Start

1. Clone the Repository

2. Install Dependencies

3. Create a Values File

4. Install Activepieces

5. Verify Installation

Production Checklist

Upgrading

Troubleshooting

Common Issues

Useful Commands

Environment Variables

Execution Modes

Uninstalling