Skip to content

Deployment Guide

Jump to bottom
jack ning edited this page Jun 15, 2026 · 1 revision

Deployment Guide

Bytedesk deployment assets are in the deploy/ directory, with Docker Compose being the most complete and recommended approach.

Deployment Directory Structure

deploy/
├── docker/           # Docker Compose configurations (recommended)
│   ├── compose-base.yaml           # Base middleware services
│   ├── compose-db-mysql.yaml       # MySQL database
│   ├── compose-db-postgresql.yaml  # PostgreSQL database
│   ├── compose-db-oracle.yaml      # Oracle database
│   ├── compose-db-kingbase9.yaml   # KingbaseES database
│   ├── compose-mq-artemis.yaml     # Artemis message queue
│   ├── compose-mq-rabbitmq.yaml    # RabbitMQ message queue
│   ├── compose-app-bytedesk.yaml   # Bytedesk application
│   ├── compose-scenario-*.yaml     # Scenario configurations
│   ├── start.sh                    # Start script
│   └── stop.sh                     # Stop script
├── kubernetes/       # Kubernetes deployment files
├── nginx/            # Nginx configuration
├── sql/              # Database initialization scripts
└── server/           # Server configuration and scripts

Docker Deployment (Recommended)

Quick Start

cd deploy/docker
cp .env.example .env
# Edit .env and update passwords and secrets

# Default: MySQL + Artemis + standard, full stack
./start.sh mysql artemis standard all

Script Format

Start Script

./start.sh <db> <mq> <scenario> <target>

Stop Script

./stop.sh <db> <mq> <scenario> <action> <target>

Parameter Options

Parameter Options Description
db mysql, postgresql, oracle, kingbase9 Database selection
mq artemis, rabbitmq Message queue selection
scenario standard, noai, call, webrtc, call-webrtc Deployment scenario
target middleware, all Deploy middleware only or full stack
action stop, down Stop containers or remove them

Common Deployment Combinations

Local Development (Middleware Only)

# MySQL + Artemis + standard (most common for development)
./start.sh mysql artemis standard middleware
./stop.sh mysql artemis standard stop middleware
./stop.sh mysql artemis standard down middleware

# PostgreSQL + RabbitMQ + noai (without AI)
./start.sh postgresql rabbitmq noai middleware
./stop.sh postgresql rabbitmq noai stop middleware

# Oracle + Artemis + noai
./start.sh oracle artemis noai middleware

# Kingbase9 + Artemis + standard
./start.sh kingbase9 artemis standard middleware

Call Center Scenarios

# Call center middleware (FreeSWITCH)
./start.sh mysql artemis call middleware
./stop.sh mysql artemis call stop middleware

# Call center full deployment
./start.sh mysql rabbitmq call all

WebRTC Video Scenarios

# WebRTC middleware (coturn + janus)
./start.sh mysql artemis webrtc middleware
./stop.sh mysql artemis webrtc stop middleware

# WebRTC full deployment
./start.sh mysql artemis webrtc all

Combined Call + WebRTC

# Both call center and WebRTC
./start.sh mysql artemis call-webrtc middleware
./stop.sh mysql artemis call-webrtc stop middleware

# Full deployment with both
./start.sh postgresql artemis call-webrtc all

Production Deployment (Full Stack)

# Standard production deployment
./start.sh mysql artemis standard all
./stop.sh mysql artemis standard stop all

# PostgreSQL + RabbitMQ production
./start.sh postgresql rabbitmq standard all

# Kingbase9 + Artemis production
./start.sh kingbase9 artemis standard all

Environment Variables

All sensitive configuration is centralized in .env. At minimum, set:

Database & MQ

  • MYSQL_ROOT_PASSWORD
  • POSTGRES_PASSWORD
  • ORACLE_PASSWORD
  • ORACLE_APP_USER_PASSWORD
  • KINGBASE_DB_PASSWORD
  • KINGBASE_SYSTEM_PWD
  • ARTEMIS_PASSWORD
  • RABBITMQ_DEFAULT_PASS

Middleware

  • REDIS_PASSWORD
  • ELASTIC_PASSWORD
  • MINIO_ROOT_PASSWORD

Application Auth

  • BYTEDESK_ADMIN_PASSWORD
  • BYTEDESK_ADMIN_VALIDATE_CODE
  • BYTEDESK_MEMBER_PASSWORD
  • BYTEDESK_JWT_SECRET_KEY

Scenario-Specific

  • COTURN_PASS - For WebRTC scenario
  • FREESWITCH_ESL_PASSWORD - For call scenario

Optional API Keys

  • SPRING_AI_*_API_KEY - AI provider keys
  • BYTEDESK_TRANSLATE_BAIDU_* - Translation service
  • BYTEDESK_LICENSE_KEY - License key (if applicable)

Important Notes

Security

  • Never commit .env to version control
  • Replace default passwords before production
  • Use separate .env files for different environments
  • Consider encrypting sensitive values (see Jasypt section below)

Database & MQ Selection

  • MySQL - Recommended default, best documentation
  • PostgreSQL - Good for teams with existing PostgreSQL infrastructure
  • Oracle/KingbaseES - For enterprise or government requirements
  • Artemis - Default message queue, recommended first choice
  • RabbitMQ - For teams with existing RabbitMQ operations

Scenario Selection

  • Start simple - Use standard or noai first
  • Add capabilities later - Add call or webrtc when needed
  • Test incrementally - Verify each scenario works before combining

Production Checklist

Before going to production:

  • Replace all default passwords in .env
  • Configure proper database persistence
  • Set up backup strategy for databases
  • Configure SSL/TLS certificates
  • Set up monitoring and alerting
  • Configure log rotation and retention
  • Set up proper network security (firewall rules)
  • Configure resource limits and autoscaling
  • Test failover and disaster recovery
  • Verify all required scenarios work correctly
  • Update admin credentials and access controls
  • Set up proper DNS and domain names
  • Configure email and notification services
  • Document the deployment configuration

Jasypt Encryption (Optional)

If you need to store encrypted values in your configuration:

# Add Jasypt password to .env (never commit real secrets)
echo 'JASYPT_ENCRYPTOR_PASSWORD=please-change-me' >> .env

# Start deployment as usual
./start.sh mysql artemis standard all
  • Leave JASYPT_ENCRYPTOR_PASSWORD blank if not using encrypted values
  • The application will fall back to plain text values automatically
  • You can override encryption algorithm with additional variables if needed

Log Management

The deployment includes Logstash and Kibana for log management:

# Logstash automatically collects logs from:
# - Docker container logs
# - Local source-run logs in starter/logs/

# View Logstash status
docker compose -p bytedesk --env-file .env -f compose-base.yaml ps bytedesk-logstash

# View Logstash logs
docker compose -p bytedesk --env-file .env -f compose-base.yaml logs -f bytedesk-logstash

# List Elasticsearch log indices
curl -u elastic:${ELASTIC_PASSWORD} http://127.0.0.1:19200/_cat/indices/bytedesk-logs-*?v

Kibana Access

First steps in Kibana:

  1. Create a data view for bytedesk-logs-*
  2. Use @timestamp as the time field
  3. Search logs by requestId, traceId, or message

Manual Docker Compose (Advanced)

If you need more control, you can use Docker Compose directly:

# Middleware only (for source development)
docker compose -p bytedesk -f compose-base.yaml -f compose-db-mysql.yaml -f compose-mq-artemis.yaml -f compose-scenario-standard.yaml up -d

# Full stack (middleware + application)
docker compose -p bytedesk -f compose-base.yaml -f compose-db-mysql.yaml -f compose-mq-artemis.yaml -f compose-scenario-standard.yaml -f compose-app-bytedesk.yaml -f compose-app-mq-artemis.yaml up -d

# With call center
docker compose -p bytedesk -f compose-base.yaml -f compose-db-postgresql.yaml -f compose-mq-artemis.yaml -f compose-scenario-call.yaml -f compose-call-db-postgresql.yaml -f compose-app-bytedesk.yaml -f compose-app-mq-artemis.yaml up -d

# Stop containers
docker compose -p bytedesk -f compose-base.yaml -f compose-db-mysql.yaml -f compose-mq-artemis.yaml -f compose-scenario-standard.yaml stop

Kubernetes Deployment

Kubernetes deployment files are in deploy/kubernetes/. See the README in that directory for details.

Nginx Configuration

Nginx configuration examples are in deploy/nginx/. Use them for:

  • Reverse proxy
  • SSL/TLS termination
  • Static file serving
  • Load balancing

Troubleshooting Deployment

Common Issues

  1. Containers not starting?

    • Check .env file permissions and format
    • Verify Docker has enough resources
    • Check port conflicts

  2. Application can't connect to database?

    • Verify database is running
    • Check network connectivity
    • Verify credentials in .env

  3. Message queue issues?

    • Check if Artemis/RabbitMQ is running
    • Verify connection settings
    • Check queue and topic configurations

  4. Scenario not working?

    • Make sure you're using the right scenario parameter
    • Verify all required containers are running
    • Check logs for scenario-specific errors

Debug Steps

# Check running containers
docker compose -p bytedesk ps

# View all logs
docker compose -p bytedesk logs -f

# View specific service logs
docker compose -p bytedesk logs -f bytedesk-mysql

# Restart a service
docker compose -p bytedesk restart bytedesk-redis

# Enter a container for debugging
docker exec -it bytedesk-mysql bash

# Go back to baseline if needed
./stop.sh mysql artemis standard down middleware
./start.sh mysql artemis standard middleware

Default Access

After deployment:

Remember to change all default credentials before production use!

Bytedesk Wiki

Getting Started

Core Documentation

Development & Deployment

External Links

Clone this wiki locally