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

   cd /Users/matt/DEV/habland
   

2. Create environment configuration

   cp .env.example .env
   nano .env  # Edit configuration values
   

3. Generate AtomCMS application key

   # You'll need to generate this after first run:
   docker compose exec atomcms php artisan key:generate
   

4. Create Docker network (if not exists)

   docker network create habbo-network
   

5. Start all services

   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

docker compose up -d

Start Specific Services

# 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

# 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

# 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

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

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

# 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

# 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

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

# 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

   docker compose logs [service-name]
   

2. Check if port is already in use

   lsof -i :3306  # Replace with your port
   

3. Rebuild service

   docker compose build --no-cache [service-name]
   docker compose up -d [service-name]
   

Database Connection Issues

1. Wait for database to be ready

   docker compose exec unified-db mysqladmin ping -proot
   

2. Check database exists

   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

   docker compose ps
   

2. Verify network connectivity

   docker compose exec cool-ui ping arcturus-emulator
   

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

Out of Memory

1. Check resource usage

   docker stats
   

2. Increase Docker memory limit (Docker Desktop Settings)

3. Adjust Java heap sizes in .env:

   JAVA_OPTS=-Xmx4G -Xms1G
   

🔄 Updates & Maintenance

Update Service Images

# 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

# 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

   docker compose build [service-name]
   

3. Restart service

   docker compose up -d [service-name]
   

Hot Reload (Development)

For services supporting hot reload, mount source as volume:

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

# 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.