# Deployment Guide

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

## Deployment Directory Structure

```text
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

```bash
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
```bash
./start.sh <db> <mq> <scenario> <target>
```

#### Stop Script
```bash
./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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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:

```bash
# 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:

```bash
# 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

- **Kibana URL**: http://127.0.0.1:15601
- **Elasticsearch**: http://127.0.0.1:19200
- **Username**: `elastic`
- **Password**: From `.env` (default: `bytedesk123`)

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:

```bash
# 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

```bash
# 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:
- **Application URL**: http://127.0.0.1:9003/ (replace with your server IP)
- **Admin Email**: admin@email.com
- **Admin Password**: admin (change this immediately!)

Remember to change all default credentials before production use!