Helm Deployment
Deploy Cherry Studio Enterprise to Kubernetes with Helm, including the API service and admin console.
Recommended: Use the Cherry Studio Agent deployment skill to automate all the steps below. See Installation and Deployment → Agent One-Click Deploy.
Features
- Dual service deployment: Deploy API and Admin simultaneously
- Independent configuration: Each service can be enabled/disabled and configured independently
- Auto scaling: Supports HPA (Horizontal Pod Autoscaler)
- Health checks: Includes liveness and readiness probes
- Ingress support: Independent Ingress rules for each service
Prerequisites
- Kubernetes 1.16+
- Helm 3.0+
- PVC support in the cluster
- A PostgreSQL database ready (see Database Configuration)
Docker Image
- Docker Hub:
cherrystudio/cherry-studio-enterprise-api - China mirror (recommended for mainland China users):
docker-registry.cherry-ai.com/public/cherry-studio-enterprise-api
Deployment Steps
Step 1: Get the Helm Chart
Choose either method:
Option A: Download ZIP
wget https://github.com/CherryInternal/cherry-studio-enterprise-helm/archive/refs/heads/main.zip
unzip main.zip
cd cherry-studio-enterprise-helm-mainOption B: Git Clone
git clone https://github.com/CherryInternal/cherry-studio-enterprise-helm.git
cd cherry-studio-enterprise-helmStep 2: Create Configuration File
The chart's default image version, database connection, and JWT secret are test values and must not be used for deployment. You must create a values-custom.yaml to override these settings.
Create a values-custom.yaml and modify the following according to your environment:
app:
# Image version (must be set explicitly, otherwise defaults to outdated v0.1.3)
image:
tag: v0.4.10
# China users can switch to the China mirror:
# repository: docker-registry.cherry-ai.com/public/cherry-studio-enterprise-api
# Replicas and autoscaling
replicaCount: 1 # Recommend 1 for data consistency
autoscaling:
enabled: false # Set to true if autoscaling is needed
# API service Ingress
api:
ingress:
enabled: true
annotations:
nginx.ingress.kubernetes.io/proxy-body-size: '20m'
hosts:
- host: api.your-domain.com # ← Replace with your API domain
paths:
- path: /
pathType: ImplementationSpecific
# Admin console Ingress
admin:
ingress:
enabled: true
annotations:
nginx.ingress.kubernetes.io/proxy-body-size: '20m'
hosts:
- host: admin.your-domain.com # ← Replace with your Admin domain
paths:
- path: /
pathType: ImplementationSpecific
# Storage configuration
persistence:
size: 20Gi
# Environment variables
env:
# Address for the admin console to reach the API:
# - With Ingress: use the API's external domain (e.g. https://api.your-domain.com)
# - Cluster-internal only: use K8s Service address (e.g. http://cherry-studio-enterprise-api:3670)
API_URL: https://api.your-domain.com # ← Replace with your API address
JWT_SECRET: 'your-secure-jwt-secret' # ← Replace with a strong random string (at least 32 chars)
DB_HOST: your-postgres-host # ← Replace with your database host
DB_PORT: '5432'
DB_USERNAME: your-username # ← Replace with your database username
DB_PASSWORD: your-password # ← Replace with your database password
DB_NAME: your-database # ← Replace with your database name
DB_TYPE: postgres
# Resource configuration (optional)
resources:
limits:
cpu: 1000m
memory: 1Gi
requests:
cpu: 200m
memory: 256MiWe recommend using Kubernetes Secrets for JWT keys and database passwords. See Production Secrets Management below.
Step 3: Install
helm install cherry-studio-enterprise ./helm -f values-custom.yaml
# Or specify a namespace
helm install cherry-studio-enterprise ./helm -f values-custom.yaml \
--namespace cherry-studio --create-namespaceStep 4: Verify Deployment
# Check pod status
kubectl get pods -l app.kubernetes.io/name=cherry-studio-enterprise
# Check service status
kubectl get svc -l app.kubernetes.io/name=cherry-studio-enterprise
# Check persistent volumes
kubectl get pvc
# Run connection test
helm test cherry-studio-enterpriseConfirm the following:
- All pods are in Running state
- Services are created with endpoints
- PVCs are bound to available PVs
- If Ingress is enabled, Ingress rules are created
Access the Application
Using Port-Forward (Testing)
# API service
kubectl port-forward svc/cherry-studio-enterprise-api 3670:3670
# Admin console
kubectl port-forward svc/cherry-studio-enterprise-admin 3680:3680Visit http://localhost:3670 (API) and http://localhost:3680 (Admin).
Using Ingress (Production)
Access via the domains configured in your values-custom.yaml:
- API service: domain set in
app.api.ingress.hosts - Admin console: domain set in
app.admin.ingress.hosts
Upgrade
Update app.image.tag in your values-custom.yaml to the target version, then run:
helm upgrade cherry-studio-enterprise ./helm -f values-custom.yamlUninstall
# Uninstall the chart
helm uninstall cherry-studio-enterprise
# Delete PVC manually (if needed)
kubectl delete pvc cherry-studio-enterprise-dataConfiguration Reference
Application Parameters
| Parameter | Description | Default |
|---|---|---|
app.enabled | Enable application | true |
app.replicaCount | Replica count | 2 |
app.image.repository | Image repository | cherrystudio/cherry-studio-enterprise-api |
app.image.tag | Image tag (falls back to Chart appVersion v0.1.3 if not set) | Not set |
app.autoscaling.enabled | Enable HPA autoscaling | true |
app.autoscaling.minReplicas | HPA minimum replicas | 1 |
app.autoscaling.maxReplicas | HPA maximum replicas | 10 |
app.api.service.type | API Service type | ClusterIP |
app.api.service.port | API service port | 3670 |
app.admin.service.type | Admin Service type | ClusterIP |
app.admin.service.port | Admin service port | 3680 |
app.persistence.enabled | Enable persistence | true |
app.persistence.size | Storage size | 10Gi |
app.persistence.accessMode | Access mode | ReadWriteOnce |
app.persistence.mountPath | Mount path | /app/data |
app.api.ingress.enabled | Enable API Ingress | true |
app.admin.ingress.enabled | Enable Admin Ingress | true |
app.resources.limits.cpu | CPU limit | 500m |
app.resources.limits.memory | Memory limit | 512Mi |
app.resources.requests.cpu | CPU request | 100m |
app.resources.requests.memory | Memory request | 128Mi |
app.env.* | Environment variables | See below |
Port Details
This application runs two services in a single container:
| Port | Service | Description |
|---|---|---|
| 3670 | API service | RESTful API |
| 3680 | Admin console | Admin UI |
Environment Variables
Configured via app.env. Key variables:
Application Configuration
| Variable | Description |
|---|---|
API_URL | Address for admin to reach the API |
API_PORT | API service port (default 3670) |
ADMIN_PORT | Admin port (default 3680) |
ADMIN_APP_NAME | Admin console name |
ADMIN_APP_LOGO_URL | Admin logo URL |
ADMIN_BASE_PATH | Admin base path (default /) |
JWT_SECRET | JWT secret (must be replaced) |
Database Configuration
| Variable | Description |
|---|---|
DB_HOST | Database host (must be replaced) |
DB_PORT | Database port (default 5432) |
DB_USERNAME | Database username (must be replaced) |
DB_PASSWORD | Database password (must be replaced) |
DB_NAME | Database name (must be replaced) |
DB_TYPE | Database type (default postgres) |
DB_SSL | Enable SSL (default false) |
Production Secrets Management
Use Kubernetes Secrets for JWT keys and database passwords:
# Create a Secret
apiVersion: v1
kind: Secret
metadata:
name: cherry-studio-jwt-secret
type: Opaque
data:
jwt-secret: <base64-encoded-strong-random-string>
---
# Reference in values-custom.yaml
app:
env:
JWT_SECRET:
valueFrom:
secretKeyRef:
name: cherry-studio-jwt-secret
key: jwt-secretRecommended Cluster Specs
| User scale | Node spec | Node count | Pod replicas | Storage |
|---|---|---|---|---|
| 0-50 | 2 vCPU, 4GB RAM | 1-2 | 1 | 10-20GB |
| 50-200 | 4 vCPU, 8GB RAM | 2-3 | 1-2 | 20-50GB |
| 200-1000 | 8 vCPU, 16GB RAM | 3-5 | 2-3 | 50-100GB |
| 2000+ | 16 vCPU, 32GB RAM | 5+ | 3-5 | 100GB+ |
Cherry Studio Enterprise is lightweight (~100-150MB memory, < 100m CPU after startup). Even small clusters can support many users.
Database recommendations:
- < 200 users: single PostgreSQL instance (2 vCPU, 4GB RAM)
- > 200 users: PostgreSQL primary-replica for availability
Troubleshooting
-
Pods stuck in Pending
- Check node resources
- Ensure PVC can be created and bound
-
Service not accessible
- Check Service and Endpoints
- Verify firewall rules
-
Data loss
- Ensure PVC is configured correctly
- Check storage class persistence support
View logs:
# View pod logs
kubectl logs -l app.kubernetes.io/name=cherry-studio-enterprise
# View pod details
kubectl describe pod -l app.kubernetes.io/name=cherry-studio-enterpriseNotes
-
Single instance: For data consistency, set
replicaCount: 1. For high availability, configure PostgreSQL primary-replica instead of multiple pods. -
Data persistence: Ensure the cluster supports persistent storage; otherwise data is lost when pods restart.
-
Network security: Use Ingress + TLS in production, restrict network access, and update image versions regularly.
Docker Deployment
Deploy Cherry Studio Enterprise with Docker and Docker Compose, featuring dual-service integration, data persistence, and health checks.
Advanced Usage
Advanced configuration options for Cherry Studio Enterprise, including database setup, SSO integration, backup and restore, and version updates.