Skip to content
Documentation

Docker Deployment

Deploy Cherry Studio Enterprise with Docker and Docker Compose, featuring dual-service integration, data persistence, and health checks.

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 integration: API service (port 3670) and admin console (port 3680) run in a single container
  • Data persistence: Supports volume mounts to keep data safe
  • Environment configuration: Flexible environment variable configuration
  • Health checks: Built-in health check mechanism
  • Auto restart: Supports container auto-restart policy

Image Registries

China mirror (recommended for users in mainland China):

docker-registry.cherry-ai.com/public/cherry-studio-enterprise-api

Docker Hub (international users):

cherrystudio/cherry-studio-enterprise-api

Users in mainland China are recommended to use the China mirror for faster and more stable image pulls.

Quick Start

Prerequisites

  • Docker 20.10+
  • Docker Compose 2.0+ (optional)
  • PostgreSQL database (production)

Using Docker Compose

services:
  api:
    image: cherrystudio/cherry-studio-enterprise-api:v0.4.10
    container_name: cherry-studio-enterprise
    ports:
      - '3670:3670'
      - '3680:3680'
    environment:
      - API_URL=https://api.demo.cherry-ai.com
      - JWT_SECRET=your-secure-jwt-secret-at-least-32-characters
      - DB_HOST=1Panel-postgresql-UmXp
      - DB_PORT=5432
      - DB_USERNAME=cherry-studio-enterprise
      - DB_PASSWORD=${DB_PASSWORD}
      - DB_NAME=cherry-studio-enterprise
      - DB_TYPE=postgres
      - DB_SSL=false
    volumes:
      - ./data:/app/data
    restart: unless-stopped

Full Production Configuration (with Database)

services:
  # PostgreSQL database
  postgres:
    image: postgres:15-alpine
    container_name: cherry-studio-enterprise-postgres
    environment:
      POSTGRES_USER: cherry-studio-enterprise
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: cherry-studio-enterprise
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - '5432:5432'
    restart: unless-stopped
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U cherry-studio-enterprise']
      interval: 10s
      timeout: 5s
      retries: 5

  # Cherry Studio API
  api:
    image: cherrystudio/cherry-studio-enterprise-api:v0.4.10
    container_name: cherry-studio-enterprise
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - '3670:3670'
      - '3680:3680'
    environment:
      # Service configuration
      - API_URL=https://api.your-domain.com
      - ADMIN_APP_NAME=Cherry Studio Enterprise

      # Security configuration
      - JWT_SECRET=${JWT_SECRET:-your-secure-jwt-secret-at-least-32-characters}

      # Database configuration
      - DB_TYPE=postgres
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_USERNAME=cherry-studio-enterprise
      - DB_PASSWORD=${POSTGRES_PASSWORD}
      - DB_NAME=cherry-studio-enterprise
      - DB_SSL=false

    volumes:
      - ./data:/app/data
      - ./logs:/app/logs

    restart: unless-stopped

    healthcheck:
      test: ['CMD', 'wget', '--quiet', '--tries=1', '--spider', 'http://localhost:3670/health']
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  postgres_data:
    driver: local

Start and Manage

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Stop and remove volumes (dangerous)
docker-compose down -v

Configuration Details

Port Mapping

Container PortServiceDescription
3670API serviceRESTful API for client calls
3680Admin consoleWeb management UI for system configuration

Environment Variables

Core Configuration

VariableDescriptionDefaultRequired
API_PORTAPI service port3670No
ADMIN_PORTAdmin console port3680No
API_URLAPI base URL-Yes
JWT_SECRETJWT secret-Yes
ADMIN_APP_NAMEAdmin app nameCherry StudioNo
ADMIN_APP_LOGO_URLAdmin logo URL-No
ADMIN_BASE_PATHAdmin base path/No

Database Configuration

VariableDescriptionDefaultNotes
DB_TYPEDatabase typepostgresOnly postgres supported
DB_HOSTDatabase host-Required for PostgreSQL
DB_PORTDatabase port5432Default PostgreSQL port
DB_USERNAMEDatabase username-Required for PostgreSQL
DB_PASSWORDDatabase password-Required for PostgreSQL
DB_NAMEDatabase name-Required for PostgreSQL
DB_SSLEnable SSLfalsePostgreSQL SSL connection

For Casdoor SSO configuration, see SSO configuration.

Data Persistence

Application data is stored under /app/data, including:

  • Uploaded files
  • Knowledge base data
  • Application configuration

We recommend mounting this directory to the host to ensure persistence:

volumes:
  - ./data:/app/data # Application data
  - ./logs:/app/logs # Log files (optional)

Deployment Best Practices

Security Configuration

JWT secret management:

# Generate a strong random secret
openssl rand -base64 32

Network Configuration

Use a custom network:

services:
  api:
    networks:
      - cherry-network

networks:
  cherry-network:
    driver: bridge

Configure a reverse proxy (Nginx):

server {
    listen 80;
    server_name api.your-domain.com;

    location / {
        proxy_pass http://localhost:3670;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name admin.your-domain.com;

    location / {
        proxy_pass http://localhost:3680;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Performance Optimization

Resource limits:

services:
  api:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

Health check configuration:

healthcheck:
  test: ['CMD', 'curl', '-f', 'http://localhost:3670/health']
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

Log Management

Configure log driver:

services:
  api:
    logging:
      driver: 'json-file'
      options:
        max-size: '10m'
        max-file: '3'

Monitoring and Maintenance

View Logs

# Tail logs in real time
docker logs -f cherry-studio-enterprise

# View last 100 lines
docker logs --tail 100 cherry-studio-enterprise

# View logs for a specific time range
docker logs --since 2024-01-01 --until 2024-01-02 cherry-studio-enterprise

Performance Monitoring

# View container resource usage
docker stats cherry-studio-enterprise

# View container details
docker inspect cherry-studio-enterprise

# Enter container for debugging
docker exec -it cherry-studio-enterprise sh

Update and Upgrade

# Pull latest image
docker-compose pull

# Stop and restart services
docker-compose down
docker-compose up -d

Troubleshooting

Common Issues

1. Container fails to start

# Check container logs
docker logs cherry-studio-enterprise

# Check port usage
netstat -tulpn | grep -E '3670|3680'

# Check Docker daemon
systemctl status docker

2. Database connection failure

  • Ensure the database service is running
  • Check network connectivity and firewall rules
  • Verify database credentials
  • Ensure the database is created and permissions are correct

3. Permission issues

# Fix data directory permissions
sudo chown -R 1000:1000 ./data

# Or fix inside the container
docker exec cherry-studio-enterprise \
  chown -R node:node /app/data

4. Out of memory

# Increase Docker memory limit
docker update --memory 4g cherry-studio-enterprise

# Or configure in docker-compose.yml
deploy:
  resources:
    limits:
      memory: 4G

Notes

  1. Production security:

    • You must change the default JWT_SECRET
    • Protect the database with strong passwords
    • Enable HTTPS/TLS
    • Regularly update image versions
  2. Data persistence:

    • Always mount data volumes to the host
  3. Performance considerations:

    • Adjust resource limits based on load
    • Use an external PostgreSQL for better performance
    • Configure appropriate health check parameters
  4. Network security:

    • Expose only necessary ports
    • Use firewall rules to restrict access
    • Use a reverse proxy in production