Skip to content
Documentation

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-main

Option B: Git Clone

git clone https://github.com/CherryInternal/cherry-studio-enterprise-helm.git
cd cherry-studio-enterprise-helm

Step 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: 256Mi

We 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-namespace

Step 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-enterprise

Confirm 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:3680

Visit 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.yaml

Uninstall

# Uninstall the chart
helm uninstall cherry-studio-enterprise

# Delete PVC manually (if needed)
kubectl delete pvc cherry-studio-enterprise-data

Configuration Reference

Application Parameters

ParameterDescriptionDefault
app.enabledEnable applicationtrue
app.replicaCountReplica count2
app.image.repositoryImage repositorycherrystudio/cherry-studio-enterprise-api
app.image.tagImage tag (falls back to Chart appVersion v0.1.3 if not set)Not set
app.autoscaling.enabledEnable HPA autoscalingtrue
app.autoscaling.minReplicasHPA minimum replicas1
app.autoscaling.maxReplicasHPA maximum replicas10
app.api.service.typeAPI Service typeClusterIP
app.api.service.portAPI service port3670
app.admin.service.typeAdmin Service typeClusterIP
app.admin.service.portAdmin service port3680
app.persistence.enabledEnable persistencetrue
app.persistence.sizeStorage size10Gi
app.persistence.accessModeAccess modeReadWriteOnce
app.persistence.mountPathMount path/app/data
app.api.ingress.enabledEnable API Ingresstrue
app.admin.ingress.enabledEnable Admin Ingresstrue
app.resources.limits.cpuCPU limit500m
app.resources.limits.memoryMemory limit512Mi
app.resources.requests.cpuCPU request100m
app.resources.requests.memoryMemory request128Mi
app.env.*Environment variablesSee below

Port Details

This application runs two services in a single container:

PortServiceDescription
3670API serviceRESTful API
3680Admin consoleAdmin UI

Environment Variables

Configured via app.env. Key variables:

Application Configuration

VariableDescription
API_URLAddress for admin to reach the API
API_PORTAPI service port (default 3670)
ADMIN_PORTAdmin port (default 3680)
ADMIN_APP_NAMEAdmin console name
ADMIN_APP_LOGO_URLAdmin logo URL
ADMIN_BASE_PATHAdmin base path (default /)
JWT_SECRETJWT secret (must be replaced)

Database Configuration

VariableDescription
DB_HOSTDatabase host (must be replaced)
DB_PORTDatabase port (default 5432)
DB_USERNAMEDatabase username (must be replaced)
DB_PASSWORDDatabase password (must be replaced)
DB_NAMEDatabase name (must be replaced)
DB_TYPEDatabase type (default postgres)
DB_SSLEnable 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-secret
User scaleNode specNode countPod replicasStorage
0-502 vCPU, 4GB RAM1-2110-20GB
50-2004 vCPU, 8GB RAM2-31-220-50GB
200-10008 vCPU, 16GB RAM3-52-350-100GB
2000+16 vCPU, 32GB RAM5+3-5100GB+

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

  1. Pods stuck in Pending

    • Check node resources
    • Ensure PVC can be created and bound
  2. Service not accessible

    • Check Service and Endpoints
    • Verify firewall rules
  3. 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-enterprise

Notes

  1. Single instance: For data consistency, set replicaCount: 1. For high availability, configure PostgreSQL primary-replica instead of multiple pods.

  2. Data persistence: Ensure the cluster supports persistent storage; otherwise data is lost when pods restart.

  3. Network security: Use Ingress + TLS in production, restrict network access, and update image versions regularly.