Archive/DOCKER_SETUP.md

# Habland Unified Docker Setup

Complete Docker orchestration for all Habbo Hotel emulators, clients, and management tools.

## 🏗️ Architecture Overview

This unified Docker Compose setup manages:

### Database Layer
- **unified-db**: MariaDB database (shared by all emulators)
- **redis**: Cache and session storage
- **phpmyadmin**: Web-based database management

### Emulator Services
- **arcturus-emulator**: Arcturus Morningstar (modern Habbo emulator)
- **havana-server**: Havana v26 emulator
- **kepler-server**: Kepler r26/r30 emulator
- **roseau-server**: Modern Java-based emulator

### Client Applications
- **cool-ui**: Modern React-based Nitro client
- **nitro-react**: Standard Nitro React client
- **havana-web**: Havana web interface
- **roseau-client**: Roseau client interface

### CMS & Assets
- **atomcms**: Laravel-based content management system
- **asset-server**: Nitro assets (SWF, furniture, etc.)

### Management Tools
- **admin-panel**: Unified control panel for all services

## 🚀 Quick Start

### Prerequisites
- Docker Engine 20.10+
- Docker Compose v2.0+
- 8GB+ RAM recommended
- 20GB+ disk space

### Initial Setup

1. **Clone and navigate to project**
   ```bash
   cd /Users/matt/DEV/habland
   ```

2. **Create environment configuration**
   ```bash
   cp .env.example .env
   nano .env  # Edit configuration values
   ```

3. **Generate AtomCMS application key**
   ```bash
   # You'll need to generate this after first run:
   docker compose exec atomcms php artisan key:generate
   ```

4. **Create Docker network** (if not exists)
   ```bash
   docker network create habbo-network
   ```

5. **Start all services**
   ```bash
   docker compose up -d
   ```

## 📊 Service Ports

| Service | Port | URL |
|---------|------|-----|
| **Databases** |
| MariaDB | 3306 | `localhost:3306` |
| Redis | 6379 | `localhost:6379` |
| phpMyAdmin | 8081 | http://localhost:8081 |
| **Emulators** |
| Arcturus Game | 30000 | `localhost:30000` |
| Arcturus RCON | 2096 | `localhost:2096` |
| Havana Game | 12321 | `localhost:12321` |
| Havana MUS | 12322 | `localhost:12322` |
| Havana RCON | 12323 | `localhost:12323` |
| Kepler Game | 12309 | `localhost:12309` |
| Kepler MUS | 12310 | `localhost:12310` |
| Roseau Game | 37120 | `localhost:37120` |
| Roseau RCON | 37119 | `localhost:37119` |
| **Clients** |
| Cool UI | 5174 | http://localhost:5174 |
| Nitro React | 5173 | http://localhost:5173 |
| Havana Web | 8084 | http://localhost:8084 |
| Roseau Client | 8082 | http://localhost:8082 |
| **CMS & Assets** |
| AtomCMS | 80/443 | http://localhost |
| Asset Server | 8083 | http://localhost:8083 |
| **Admin** |
| Admin Panel | 3000 | http://localhost:3000 |

## 🎮 Managing Services

### Start All Services
```bash
docker compose up -d
```

### Start Specific Services
```bash
# Start only Arcturus and its dependencies
docker compose up -d arcturus-emulator cool-ui asset-server unified-db

# Start only Havana stack
docker compose up -d havana-server havana-web unified-db

# Start only Kepler
docker compose up -d kepler-server unified-db

# Start only Roseau
docker compose up -d roseau-server roseau-client unified-db
```

### Stop Services
```bash
# Stop all
docker compose down

# Stop specific service
docker compose stop arcturus-emulator

# Stop and remove volumes (WARNING: deletes data)
docker compose down -v
```

### View Logs
```bash
# All services
docker compose logs -f

# Specific service
docker compose logs -f arcturus-emulator
docker compose logs -f havana-server
docker compose logs -f unified-db

# Last 100 lines
docker compose logs --tail=100 arcturus-emulator
```

### Restart Services
```bash
# Restart all
docker compose restart

# Restart specific service
docker compose restart arcturus-emulator
```

## 🗄️ Database Management

### Database Initialization

The `unified-db/init/` directory contains SQL initialization scripts that run on first startup:

```bash
unified-db/init/
  ├── 01-create-databases.sql      # Creates all databases
  ├── 02-arcturus-schema.sql       # Arcturus tables
  ├── 03-havana-schema.sql         # Havana tables
  ├── 04-kepler-schema.sql         # Kepler tables
  ├── 05-roseau-schema.sql         # Roseau tables
  └── 06-atomcms-schema.sql        # AtomCMS tables
```

### Connect to Database
```bash
# Using phpMyAdmin
open http://localhost:8081

# Using CLI
docker compose exec unified-db mysql -uroot -proot

# Using external client
Host: localhost
Port: 3306
User: root
Password: root
```

### Backup Database
```bash
# Backup all databases
docker compose exec unified-db mysqldump -uroot -proot --all-databases > backup.sql

# Backup specific database
docker compose exec unified-db mysqldump -uroot -proot havana > havana-backup.sql
```

### Restore Database
```bash
# Restore from backup
docker compose exec -T unified-db mysql -uroot -proot < backup.sql

# Restore specific database
docker compose exec -T unified-db mysql -uroot -proot havana < havana-backup.sql
```

## 🔧 Configuration

### Emulator Configuration Files

Each emulator has its own configuration:

- **Arcturus**: `retro/emulator/config.docker.ini`
- **Havana**: `havana/Havana_Repo/config/`
- **Kepler**: `kepler/Kepler-Server/config/`
- **Roseau**: `roseau/roseau.properties`, `roseau/habbohotel.properties`

### Environment Variables

Edit `.env` file to configure:

```bash
# Database credentials
MYSQL_ROOT_PASSWORD=your_secure_password

# Service-specific settings
ATOMCMS_APP_NAME=MyHabboRetro
ATOMCMS_URL=https://myretro.com

# Enable/disable services
ENABLE_ARCTURUS=true
ENABLE_HAVANA=false
```

## 🐛 Troubleshooting

### Service Won't Start

1. **Check logs**
   ```bash
   docker compose logs [service-name]
   ```

2. **Check if port is already in use**
   ```bash
   lsof -i :3306  # Replace with your port
   ```

3. **Rebuild service**
   ```bash
   docker compose build --no-cache [service-name]
   docker compose up -d [service-name]
   ```

### Database Connection Issues

1. **Wait for database to be ready**
   ```bash
   docker compose exec unified-db mysqladmin ping -proot
   ```

2. **Check database exists**
   ```bash
   docker compose exec unified-db mysql -uroot -proot -e "SHOW DATABASES;"
   ```

3. **Verify credentials in emulator config**

### Client Can't Connect to Emulator

1. **Check emulator is running**
   ```bash
   docker compose ps
   ```

2. **Verify network connectivity**
   ```bash
   docker compose exec cool-ui ping arcturus-emulator
   ```

3. **Check client configuration** (API URLs, WebSocket URLs)

### Out of Memory

1. **Check resource usage**
   ```bash
   docker stats
   ```

2. **Increase Docker memory limit** (Docker Desktop Settings)

3. **Adjust Java heap sizes** in `.env`:
   ```bash
   JAVA_OPTS=-Xmx4G -Xms1G
   ```

## 🔄 Updates & Maintenance

### Update Service Images
```bash
# Pull latest images
docker compose pull

# Rebuild custom images
docker compose build --no-cache

# Restart with new images
docker compose up -d
```

### Clean Up Unused Resources
```bash
# Remove stopped containers
docker compose rm

# Remove unused images
docker image prune -a

# Remove unused volumes (WARNING: may delete data)
docker volume prune
```

## 📦 Development Workflow

### Making Changes to Services

1. **Edit source code** in respective directories
2. **Rebuild affected service**
   ```bash
   docker compose build [service-name]
   ```
3. **Restart service**
   ```bash
   docker compose up -d [service-name]
   ```

### Hot Reload (Development)

For services supporting hot reload, mount source as volume:

```yaml
services:
  cool-ui:
    volumes:
      - ./retro/cool-ui/src:/app/src  # Enable hot reload
```

## 🔐 Security Considerations

### Production Deployment

1. **Change default passwords** in `.env`
2. **Use secrets** for sensitive data
3. **Enable HTTPS** for web services
4. **Restrict database access** (bind to localhost only)
5. **Use firewall rules** to limit port exposure
6. **Regular backups** of database and volumes

### Network Security

```yaml
# Example: Restrict database to internal network only
services:
  unified-db:
    ports: []  # Remove external port exposure
```

## 📝 Notes

- All services use the shared `habbo-network` Docker network
- Database is shared across all emulators (separate databases per emulator)
- Logs are persisted in named volumes
- First startup may take 5-10 minutes for database initialization
- AtomCMS requires `php artisan key:generate` after first run

## 🆘 Support

For issues or questions:
1. Check logs: `docker compose logs -f`
2. Verify configuration files
3. Ensure all ports are available
4. Check Docker daemon is running
5. Verify sufficient system resources

## 📄 License

See individual service directories for licensing information.