Deploy on Kubernetes

OpenPanel can be deployed on Kubernetes using the community-maintained Helm chart. This allows you to run OpenPanel in a scalable, production-ready Kubernetes environment.

The Helm chart is maintained by the community and available on Artifact Hub.

Prerequisites

Kubernetes 1.19+
Helm 3.0+
kubectl configured to access your cluster
At least 2GB RAM per node (4GB+ recommended)
Persistent volume support (if using self-hosted databases)

Quick Start

Add the Helm Repository

Add the OpenPanel Helm repository:

helm repo add openpanel https://yashGoyal40.github.io/openpanel
helm repo update

Download Default Values

Download the default values file to customize your configuration:

helm show values openpanel/openpanel > my-values.yaml

⚠️ IMPORTANT: Before installing, you MUST configure the required values in values.yaml. The chart includes placeholder values (marked with <>) that will cause the installation to fail if not properly configured.

Configure Required Values

Edit my-values.yaml and configure the following required values:

Ingress Configuration:

ingress:
  enabled: true
  type: standard  # or "httpproxy" for Contour
  fqdn: your-domain.com  # Replace with your actual domain
  standard:
    tlsSecretName: openpanel-tls

Application URLs:

config:
  apiUrl: "https://your-domain.com/api"
  dashboardUrl: "https://your-domain.com"
  googleRedirectUri: "https://your-domain.com/api/oauth/google/callback"

Cookie Secret (generate with openssl rand -base64 32):

secrets:
  cookieSecret: "YOUR_GENERATED_SECRET_HERE"

PostgreSQL Configuration (choose one):

Option A: External PostgreSQL (recommended for production)

postgresql:
  enabled: false
externalPostgresql:
  host: "postgres.example.com"
  port: 5432
  user: "openpanel"
  password: "your-secure-password"
  database: "openpanel"
  schema: public

Option B: Self-hosted PostgreSQL

postgresql:
  enabled: true
  user: postgres
  password: "your-secure-password"
  database: postgres
  persistence:
    size: 20Gi

Install OpenPanel

Install OpenPanel with your configured values:

helm install my-openpanel openpanel/openpanel \
  --version 0.1.0 \
  --namespace openpanel \
  --create-namespace \
  -f my-values.yaml

Or override specific values directly:

helm install my-openpanel openpanel/openpanel \
  --version 0.1.0 \
  --namespace openpanel \
  --create-namespace \
  --set ingress.fqdn=your-domain.com \
  --set config.apiUrl=https://your-domain.com/api \
  --set secrets.cookieSecret=$(openssl rand -base64 32)

Verify Installation

Check that all pods are running:

kubectl get pods -n openpanel

You should see pods for:

API server (op-api)
Dashboard (op-dashboard)
Worker (op-worker)
PostgreSQL (if using self-hosted)
Redis (if using self-hosted)
ClickHouse (if using self-hosted)

Check the status:

kubectl get all -n openpanel

Access Your Dashboard

Once all pods are running, access OpenPanel at your configured domain. The ingress will route traffic to the dashboard service.

If you need to test locally, you can port-forward:

kubectl port-forward svc/op-dashboard 3000:80 -n openpanel

Then access OpenPanel at http://localhost:3000.

Configuration

Required Configuration

The following values MUST be configured before installation:

Configuration	Required	Placeholder	Description
`ingress.fqdn`	✅ Yes	`<fqdn>`	Your domain name
`ingress.*.tlsSecretName`	✅ Yes	`<tls_secret_name>`	TLS certificate secret name
`config.apiUrl`	✅ Yes	`<fqdn>`	Full API URL
`config.dashboardUrl`	✅ Yes	`<fqdn>`	Full Dashboard URL
`config.googleRedirectUri`	✅ Yes	`<fqdn>`	OAuth callback URL
`secrets.cookieSecret`	✅ Yes	`CHANGE_ME_...`	Session encryption key
`externalPostgresql.*`	⚠️ If external	`<postgres_*>`	PostgreSQL connection details

Complete Example Configuration

Here's a minimal example configuration file (my-values.yaml) with all required values:

my-values.yaml

# Ingress Configuration
ingress:
  enabled: true
  type: standard  # or "httpproxy" for Contour
  fqdn: analytics.example.com
  standard:
    tlsSecretName: openpanel-tls

# Application URLs
config:
  apiUrl: "https://analytics.example.com/api"
  dashboardUrl: "https://analytics.example.com"
  googleRedirectUri: "https://analytics.example.com/api/oauth/google/callback"

# Cookie Secret (generate with: openssl rand -base64 32)
secrets:
  cookieSecret: "YOUR_GENERATED_SECRET_HERE"

# PostgreSQL - Using External Database
postgresql:
  enabled: false

externalPostgresql:
  host: "postgres.example.com"
  port: 5432
  user: "openpanel"
  password: "your-secure-password"
  database: "openpanel"
  schema: public

Optional Configuration

The Helm chart maps environment variables to Helm values. For a complete reference of all available environment variables and their descriptions, see the Environment Variables documentation.

Email Configuration

Enable email functionality (password resets, invitations, etc.):

secrets:
  resendApiKey: "re_xxxxxxxxxxxxx"  # Your Resend API key
  emailSender: "noreply@your-domain.com"  # Verified sender email

Get your Resend API key from resend.com. Make sure to verify your sender email domain.

AI Features

Enable AI-powered features:

config:
  aiModel: "gpt-4o-mini"  # Options: gpt-4o, gpt-4o-mini, claude-3-5

secrets:
  openaiApiKey: "sk-xxxxxxxxxxxxx"  # For OpenAI models
  anthropicApiKey: ""  # For Claude models (leave empty if not using)
  geminiApiKey: ""  # For Gemini models (leave empty if not using)

You only need to configure the API key for the model you choose. Leave other API keys as empty strings ("") if not using them.

Google OAuth

Enable Google OAuth login:

secrets:
  googleClientId: "xxxxx.apps.googleusercontent.com"
  googleClientSecret: "GOCSPX-xxxxxxxxxxxxx"

Set up Google OAuth in Google Cloud Console. Add authorized redirect URI: https://your-domain.com/api/oauth/google/callback

Redis Configuration

Redis is enabled by default and deployed within Kubernetes. To use an external Redis instance:

redis:
  enabled: false

externalRedis:
  host: "redis.example.com"
  port: 6379

ClickHouse Configuration

ClickHouse is enabled by default and deployed within Kubernetes. To use an external ClickHouse instance:

clickhouse:
  enabled: false

externalClickhouse:
  host: "clickhouse.example.com"
  port: 8123
  database: openpanel

Application Components

Enable/disable individual components:

api:
  enabled: true
  replicas: 1

dashboard:
  enabled: true
  replicas: 1

worker:
  enabled: true
  replicas: 1

Resource Limits

Adjust resource requests and limits:

api:
  resources:
    requests:
      memory: "512Mi"
      cpu: "250m"
    limits:
      memory: "2Gi"
      cpu: "2000m"

Updating OpenPanel

To upgrade to a newer version:

helm repo update
helm upgrade my-openpanel openpanel/openpanel \
  --version <new-version> \
  --namespace openpanel \
  -f my-values.yaml

Replace <new-version> with the desired version number (e.g., 0.1.1).

Managing Your Deployment

View Logs

View logs from specific deployments:

# API logs
kubectl logs -f deployment/op-api -n openpanel

# Dashboard logs
kubectl logs -f deployment/op-dashboard -n openpanel

# Worker logs
kubectl logs -f deployment/op-worker -n openpanel

Restart Services

Restart a specific deployment:

kubectl rollout restart deployment/op-api -n openpanel
kubectl rollout restart deployment/op-dashboard -n openpanel
kubectl rollout restart deployment/op-worker -n openpanel

Scale Services

Scale services on the fly:

kubectl scale deployment/op-worker --replicas=3 -n openpanel

Or update your values file and upgrade:

worker:
  replicas: 3

helm upgrade my-openpanel openpanel/openpanel -f my-values.yaml -n openpanel

Check Services

View all services:

kubectl get svc -n openpanel

Check ConfigMap and Secrets

Verify configuration:

kubectl get configmap openpanel-config -n openpanel -o yaml
kubectl get secret openpanel-secrets -n openpanel -o yaml

Ingress Configuration

Standard Ingress (NGINX/Traefik)

ingress:
  enabled: true
  type: standard
  fqdn: openpanel.your-domain.com
  standard:
    tlsSecretName: openpanel-tls
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
      nginx.ingress.kubernetes.io/ssl-redirect: "true"

HTTPProxy (Contour)

ingress:
  enabled: true
  type: httpproxy
  fqdn: openpanel.your-domain.com
  httpproxy:
    tlsSecretName: openpanel-tls

Troubleshooting

Pods Not Starting

Check pod status:

kubectl describe pod <pod-name> -n openpanel

Check events:

kubectl get events --sort-by='.lastTimestamp' -n openpanel

Check logs:
```
kubectl logs <pod-name> -n openpanel
```

Database Connection Issues

Verify database pods are running (if using self-hosted):
```
kubectl get pods -n openpanel | grep postgres
```

Check database service:

kubectl get svc -n openpanel | grep postgres

Test database connection:

kubectl exec -it deployment/op-api -n openpanel -- env | grep DATABASE_URL

Configuration Issues

If pods are failing due to configuration:

Verify all required values are set:

helm get values my-openpanel -n openpanel

Check for placeholder values:

helm get values my-openpanel -n openpanel | grep "<"

Ensure secrets are properly set:

kubectl get secret openpanel-secrets -n openpanel -o yaml

Ingress Not Working

Check ingress status:

kubectl get ingress -n openpanel
kubectl describe ingress -n openpanel

Verify ingress controller is running:

kubectl get pods -n ingress-nginx  # For NGINX
# or
kubectl get pods -n projectcontour  # For Contour

Check DNS configuration

Backup and Restore

Backup PostgreSQL

If using self-hosted PostgreSQL:

kubectl exec -it <postgresql-pod-name> -n openpanel -- \
  pg_dump -U postgres openpanel > backup.sql

Or use a Kubernetes CronJob for automated backups.

Restore PostgreSQL

Restore from backup:

kubectl exec -i <postgresql-pod-name> -n openpanel -- \
  psql -U postgres openpanel < backup.sql

Uninstalling

To uninstall OpenPanel:

helm uninstall my-openpanel --namespace openpanel

⚠️ Warning: This will delete all resources including persistent volumes. Make sure to backup your data before uninstalling!

To keep persistent volumes:

# Delete the release but keep PVCs
helm uninstall my-openpanel --namespace openpanel

# Manually delete PVCs if needed
kubectl delete pvc -l app.kubernetes.io/name=openpanel -n openpanel

Next Steps

Configure email settings for password resets and invitations
Set up AI integration for the analytics assistant
Configure SDK to track events from your applications

Deploy on Kubernetes

On this page