MySQL 8.0 Database
- 174 tables with complete schema
- 51,678 furniture items (99.93% English)
- 2,311 catalog pages (100% English)
- User accounts and settings
- Room layouts and navigator data
Arcturus Morningstar Emulator
- Version: 3.6.1
- Plugins: 84 installed
- WebSocket support enabled
- Java 21 runtime
Nitro Clients
- Cool UI (Primary) - Modern React-based client
- Standard Nitro (Alternative) - Classic Nitro experience
Asset Server
- 695MB of game assets
- Catalogue icons: 5,655 files
- Images, sounds, gamedata
- CORS enabled for cross-origin requests
AtomCMS
- Laravel-based hotel management
- User registration and management
- Admin panel
- News and articles system

Catalog Translation Status

✅ Completed Translations:

Catalog pages: 2,311/2,311 (100%)
Catalog items: 51,643/51,678 (99.93%)

⚠️ Remaining Items (32 items with proper names):

Pokémon displays (21 items - kept accented for authenticity)
Café themed items (6 items - proper noun)
Piñata items (3 items - proper noun)
Misc proper nouns (2 items)

🗄️ Database Information

Connection Details

Docker Environment (Port 3307):

Host: localhost
Port: 3307
Database: habbo_retro
Username: habbo_user
Password: habbo_password_2024
Character Set: utf8mb4
Collation: utf8mb4_unicode_ci

Local MySQL (if running non-Docker):

Host: localhost
Port: 3306
Database: habbo_retro
Username: habbo_user
Password: habbo_password_2024

Database Structure

Key Tables:

User Management:
├── users (user accounts)
├── users_settings (preferences)
└── user_ai_settings (AI provider settings)

Catalog System:
├── catalog_items (51,678 items - English)
├── catalog_pages (2,311 pages - English)
├── catalog_pages_backup (original Spanish backup)
├── catalog_items_backup (pre-translation backup)
└── catalog_items_backup_translation (translation checkpoint)

Game Data:
├── items (furniture instances)
├── rooms (user rooms)
├── room_models (room layouts)
└── navigator_publics (public rooms)

Emulator:
├── emulator_texts (server messages - 956 entries)
├── emulator_settings (configuration)
└── permissions (user ranks)

Website/CMS:
├── website_languages (language support)
└── website_settings (CMS configuration)

Quick Database Queries

-- Count all tables
SELECT COUNT(*) FROM information_schema.tables
WHERE table_schema='habbo_retro';
-- Expected: 174

-- Count catalog items
SELECT COUNT(*) FROM catalog_items;
-- Expected: 51,678

-- Count catalog pages
SELECT COUNT(*) FROM catalog_pages;
-- Expected: 2,311

-- View user count
SELECT COUNT(*) FROM users;

-- Check catalog translation status
SELECT COUNT(*) as translated
FROM catalog_items
WHERE catalog_name NOT REGEXP '[áéíóúñÁÉÍÓÚÑ¿¡]';
-- Expected: 51,643 (99.93%)

🚀 Quick Start

Prerequisites

Docker Desktop 20.10+ (Download)
Docker Compose 2.0+
4GB RAM minimum (8GB recommended)
10GB free disk space

Option 1: Using Helper Scripts (Recommended)

# Navigate to project directory
cd /Users/matt/DEV/retro

# Start all services
./docker-start.sh

# View logs
./docker-logs.sh

# Stop all services
./docker-stop.sh

# Create database backup
./docker-backup.sh

Option 2: Using Docker Compose Directly

# Build all containers
docker-compose build

# Start all services
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

First Time Setup

Start Services:
```
./docker-start.sh
```
Wait for Services (10-15 seconds):
- MySQL: Initializing database
- Emulator: Loading plugins
- Clients: Starting nginx
Verify All Services Running:
```
docker-compose ps
```
All services should show "Up" or "healthy" status.
Access the Hotel:
- Open browser: http://localhost:5174 (Cool UI)
- Or: http://localhost:5173 (Nitro React)

🌐 Service URLs

Client Access

Service	URL	Description
Cool UI	http://localhost:5174	Primary Nitro client (recommended)
Nitro React	http://localhost:5173	Alternative Nitro client
Asset Server	http://localhost:8081	Game assets and resources
CMS	http://localhost	Web interface (needs setup)

Server Connections

Service	Host	Port	Description
MySQL	localhost	3307	Database server
Emulator (Game)	localhost	30000	Game server connection
Emulator (WebSocket)	localhost	2096	WebSocket connection

Useful Endpoints

Asset Server:

Gamedata: http://localhost:8081/gamedata/
Catalog Icons: http://localhost:8081/c_images/catalogue/
UI Texts: http://localhost:8081/gamedata/UITexts.json
Renderer Config: http://localhost:8081/gamedata/renderer-config.json

Health Checks:

Cool UI: http://localhost:5174/health
Nitro React: http://localhost:5173/health
Asset Server: http://localhost:8081/health

MySQL Database

Root User:

Username: root
Password: root_password_2024

Application User:

Username: habbo_user
Password: habbo_password_2024
Database: habbo_retro

Hotel Users

Check your database for existing users:

SELECT id, username, mail, rank
FROM users
ORDER BY id
LIMIT 10;

Note: If no users exist, register through the CMS or create one directly in the database.

AtomCMS Admin

Default Laravel Admin (if created):

Email: admin@localhost
Password: (check your local installation)

Note: AtomCMS requires local setup. See Development section.

🐳 Docker Services

Service Details

1. MySQL Database

Container: habbo-mysql
Image: mysql:8.0
Port: 3307 → 3306
Memory: ~200MB
Data Volume: habbo-retro_mysql_data
Config: mysql/conf.d/custom.cnf

Features:

UTF8MB4 character encoding
512MB InnoDB buffer pool
Binary logging enabled
Slow query logging enabled

2. Arcturus Emulator

Container: habbo-emulator
Image: eclipse-temurin:21-jre
Ports: 30000 (game), 2096 (WebSocket)
Memory: ~400MB
Heap Size: 512MB - 2GB
Plugins: 84

Configuration: emulator/config.docker.ini

3. Asset Server

Container: habbo-asset-server
Image: nginx:alpine
Port: 8081 → 80
Memory: ~10MB
Assets: 695MB

Features:

CORS enabled (wildcard)
30-day caching
Gzip compression

4. Cool UI (Primary Client)

Container: habbo-cool-ui
Image: nginx:alpine
Port: 5174 → 80
Memory: ~5MB
Bundle Size: ~3MB

5. Nitro React (Alternative Client)

Container: habbo-nitro-react
Image: nginx:alpine
Port: 5173 → 80
Memory: ~5MB

6. AtomCMS

Container: habbo-cms
Image: php:8.4-fpm + nginx
Ports: 80, 443
Memory: ~150MB
Status: ⚠️ Requires local composer install

Resource Usage Summary

Total Resources:

RAM: ~770MB
Disk: ~2.5GB (images + volumes)
CPU: Minimal (<10% idle)

Startup Time:

Cold start: ~12 seconds
Warm start: ~5 seconds

📁 File Structure

/Users/matt/DEV/retro/
│
├── README.md                          # This file
├── docker-compose.yml                 # Service orchestration
├── .env                               # Environment variables
├── .env.docker                        # Environment template
│
├── docker-*.sh                        # Helper scripts
│   ├── docker-start.sh               # Start all services
│   ├── docker-stop.sh                # Stop all services
│   ├── docker-logs.sh                # View service logs
│   ├── docker-backup.sh              # Backup database
│   └── verify-docker-setup.sh        # Verify installation
│
├── database_backup/                   # Database backups
│   ├── habbo_retro_complete_20251206_155812.sql      (29 MB)
│   ├── habbo_retro_complete_20251206_155812.sql.gz   (3.3 MB)
│   └── MIGRATION_GUIDE.txt           # Migration instructions
│
├── mysql/                             # MySQL configuration
│   ├── Dockerfile
│   ├── conf.d/
│   │   └── custom.cnf                # Performance tuning
│   └── init/
│       └── habbo_retro_*.sql         # Database dump
│
├── emulator/                          # Arcturus Emulator
│   ├── Dockerfile
│   ├── config.ini                    # Local config
│   ├── config.docker.ini             # Docker config
│   ├── Habbo-3.6.0-jar-with-dependencies.jar
│   └── plugins/                      # 84 plugins
│
├── Nitro-Cool-UI/                    # Cool UI client
│   ├── dist/                         # Built files
│   ├── src/
│   └── public/
│       └── ui-config.json            # Client configuration
│
├── nitro-react/nitro-react/          # Standard Nitro client
│   ├── dist/                         # Built files
│   └── public/
│
├── nitro-assets/nitro-assets/        # Game assets (695 MB)
│   ├── c_images/                     # Catalogue icons (5,655 files)
│   ├── gamedata/                     # JSON configs
│   ├── images/                       # UI images
│   ├── sounds/                       # Audio files
│   └── bundled/                      # Compiled assets
│
├── atomcms/                          # AtomCMS
│   ├── app/
│   ├── public/
│   ├── .env                          # CMS configuration
│   └── vendor/                       # PHP dependencies
│
├── cool-ui/                          # Cool UI Docker config
│   ├── Dockerfile.simple
│   └── nginx.conf
│
├── nitro-react/                      # Nitro React Docker config
│   ├── Dockerfile.simple
│   └── nginx.conf
│
├── asset-server/                     # Asset server config
│   ├── Dockerfile
│   └── nginx.conf
│
├── cms/docker/                       # CMS Docker config
│   ├── Dockerfile
│   ├── nginx-site.conf
│   └── supervisord.conf
│
└── Documentation/
    ├── DOCKER_README.md              # Docker deployment guide
    ├── DOCKER_TEST_REPORT.md         # Test results
    ├── DOCKER_FIXES_SUMMARY.md       # Applied fixes
    ├── DOCKER_DEPLOYMENT_PLAN.md     # Original plan
    └── DOCKER_DEPLOYMENT_SUMMARY.md  # Implementation details

💾 Database Backup & Migration

Location of Database Dump

The complete database backup is located at:

/Users/matt/DEV/retro/database_backup/

Files:

habbo_retro_complete_20251206_155812.sql (29 MB)
- Full SQL dump with all data
- Includes all 174 tables
- Complete INSERT statements
- Stored procedures and triggers
habbo_retro_complete_20251206_155812.sql.gz (3.3 MB)
- Compressed version for transfer
- Recommended for server migration
MIGRATION_GUIDE.txt
- Step-by-step migration instructions
- Server setup commands
- Troubleshooting tips

Database Backup Details

Backup Information:

Created: December 6, 2025 15:58:12
MySQL Version: 9.5.0 (export server)
Compatible With: MySQL 5.7+, MariaDB 10.2+
Character Set: utf8mb4
Collation: utf8mb4_unicode_ci

Contents:

✅ All table structures (CREATE TABLE)
✅ All table data (INSERT statements)
✅ Stored procedures and functions
✅ Triggers
✅ Complete column names in inserts
✅ Drop table statements (clean import)

Creating New Backups

Using Helper Script:

./docker-backup.sh

Backups are saved to: ./docker-backups/habbo_retro_YYYYMMDD_HHMMSS.sql.gz

Manual Backup:

docker-compose exec -T mysql mysqldump \
  -u habbo_user \
  -phabbo_password_2024 \
  habbo_retro \
  --routines \
  --triggers \
  --single-transaction \
  > backup_$(date +%Y%m%d).sql

# Compress
gzip backup_$(date +%Y%m%d).sql

Restoring from Backup

Restore to Docker MySQL:

# Method 1: Using compressed backup
gunzip habbo_retro_complete_20251206_155812.sql.gz
docker-compose exec -T mysql mysql \
  -u habbo_user \
  -phabbo_password_2024 \
  habbo_retro < habbo_retro_complete_20251206_155812.sql

# Method 2: Using uncompressed
docker-compose exec -T mysql mysql \
  -u habbo_user \
  -phabbo_password_2024 \
  habbo_retro < database_backup/habbo_retro_complete_20251206_155812.sql

Restore to Local MySQL:

mysql -u habbo_user -phabbo_password_2024 habbo_retro \
  < database_backup/habbo_retro_complete_20251206_155812.sql

Migrating to New Server

See: database_backup/MIGRATION_GUIDE.txt for detailed instructions.

Quick Migration:

Upload compressed backup to new server
Extract: gunzip habbo_retro_complete_20251206_155812.sql.gz
Create database and user
Import: mysql -u user -p database < backup.sql
Update configuration files
Start services

🔧 Development

Running Services Locally (Non-Docker)

MySQL Database

# Start local MySQL
mysql.server start  # macOS
# or
sudo systemctl start mysql  # Linux

# Connect
mysql -u habbo_user -phabbo_password_2024 habbo_retro

Arcturus Emulator

cd emulator
java -Xmx2G -Xms512M -jar Habbo-3.6.0-jar-with-dependencies.jar

Cool UI

cd Nitro-Cool-UI
npm install
npm run dev
# Access: http://localhost:5174

Nitro React

cd nitro-react/nitro-react
npm install
npm run dev
# Access: http://localhost:5173

Asset Server

cd nitro-assets/nitro-assets
npx http-server -p 8080 --cors='*'
# Access: http://localhost:8080

AtomCMS

cd atomcms

# First time setup
composer install
php artisan key:generate
php artisan migrate

# Start server
php artisan serve
# Access: http://localhost:8000

Configuration Files

Emulator (emulator/config.ini):

[database]
db.hostname=localhost      # Use "mysql" for Docker
db.port=3306
db.username=habbo_user
db.password=habbo_password_2024
db.database=habbo_retro

[game]
game.host=0.0.0.0
game.port=30000

[websockets]
ws.nitro.enabled=true
ws.nitro.port=2096

Cool UI (Nitro-Cool-UI/public/ui-config.json):

{
  "camera.url": "http://localhost/swf/usercontent/camera",
  "url.prefix": "http://localhost"
}

AtomCMS (atomcms/.env):

DB_CONNECTION=mysql
DB_HOST=localhost          # Use "mysql" for Docker
DB_PORT=3306              # Use 3307 for Docker
DB_DATABASE=habbo_retro
DB_USERNAME=habbo_user
DB_PASSWORD=habbo_password_2024

Building Docker Images

# Build specific service
docker-compose build mysql
docker-compose build emulator
docker-compose build cool-ui

# Build all services
docker-compose build

# Build without cache
docker-compose build --no-cache

🔍 Troubleshooting

Services Won't Start

Check Docker is running:

docker info

Check port conflicts:

lsof -i :3307  # MySQL
lsof -i :5174  # Cool UI
lsof -i :5173  # Nitro React
lsof -i :8081  # Assets
lsof -i :30000 # Emulator

View service logs:

./docker-logs.sh [service-name]
# or
docker-compose logs mysql
docker-compose logs emulator
docker-compose logs cool-ui

Emulator Can't Connect to Database

Check MySQL is healthy:

docker-compose ps mysql
# Should show "healthy"

Test database connection:

docker-compose exec mysql mysql -u habbo_user -phabbo_password_2024 -e "SELECT 1"

Verify emulator config:

docker-compose exec emulator cat /emulator/config.ini | grep db.hostname
# Should show: db.hostname=mysql

Client Shows Blank Page

Check asset server:

curl http://localhost:8081/gamedata/UITexts.json
# Should return JSON

Check browser console for errors

Verify CORS:

curl -I -H "Origin: http://localhost:5174" \
  http://localhost:8081/gamedata/UITexts.json | grep Access-Control
# Should show: Access-Control-Allow-Origin: *

Database Import Fails

Check character encoding:

SHOW VARIABLES LIKE 'character_set%';
# Should all be utf8mb4

Import with specific encoding:

docker-compose exec -T mysql mysql \
  -u habbo_user \
  -phabbo_password_2024 \
  --default-character-set=utf8mb4 \
  habbo_retro < backup.sql

CMS Shows 500 Error

Check Laravel logs:

docker-compose exec cms tail -f /var/www/html/storage/logs/laravel.log

Clear Laravel cache:

docker-compose exec cms php artisan cache:clear
docker-compose exec cms php artisan config:clear
docker-compose exec cms php artisan view:clear

Fix: Install composer dependencies locally:

cd atomcms
composer install --no-dev --optimize-autoloader
# Then rebuild: docker-compose build cms

Port Already in Use

Change port mapping in docker-compose.yml:

ports:
  - "5175:80"  # Changed from 5174:80

Reset Everything

# Stop all services
docker-compose down

# Remove all volumes (⚠️ DELETES ALL DATA)
docker-compose down -v

# Remove all images
docker-compose down --rmi all

# Start fresh
docker-compose up -d

🚀 Production Deployment

Pre-Deployment Checklist

Change all default passwords in .env
Set APP_DEBUG=false in CMS .env
Generate new APP_KEY for Laravel
Configure SSL certificates
Set up automated database backups
Configure firewall rules
Set up monitoring and alerting
Test backup restoration procedure
Document your custom configuration
Create admin accounts
Test all services under load

Security Recommendations

1. Change Default Passwords:

# .env
MYSQL_ROOT_PASSWORD=<strong-random-password>
MYSQL_PASSWORD=<strong-random-password>
APP_KEY=base64:<generated-key>

2. Restrict Database Access:

# docker-compose.yml
mysql:
  environment:
    - MYSQL_ROOT_HOST=127.0.0.1  # Restrict to localhost

3. Enable SSL for CMS:

Configure nginx SSL certificates
Use Let's Encrypt for free SSL
Redirect HTTP to HTTPS

4. Firewall Configuration:

# Only expose necessary ports
# Block: 3307 (MySQL - internal only)
# Allow: 80, 443 (CMS)
# Allow: 30000, 2096 (Emulator)
# Allow: 5173, 5174 (Clients)

5. Regular Backups:

# Add to crontab
0 2 * * * cd /path/to/retro && ./docker-backup.sh

Performance Optimization

MySQL Configuration (mysql/conf.d/custom.cnf):

innodb_buffer_pool_size = 1G  # Increase for production
max_connections = 500

Docker Resource Limits (docker-compose.yml):

services:
  mysql:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          memory: 1G

Monitoring

Health Checks:

# All services
docker-compose ps

# Specific health check
curl http://localhost:5174/health

Resource Usage:

docker stats

Logs:

# Aggregate logs
docker-compose logs -f > hotel.log

# Service-specific
docker-compose logs -f emulator > emulator.log

📊 Project Statistics

Translation Achievement

Total Items: 51,678
Translated: 51,643 (99.93%)
Original Language: Spanish
Target Language: English
Translation Method:
- Automated: 1,493 items (MyMemory API)
- Manual (Gemini): 3,655 items (6 batches)
- Final round: 40 items
- Remaining: 32 proper nouns with accents

Database Metrics

Tables: 174
Size (Uncompressed): 51 MB
Size (SQL Dump): 29 MB
Size (Compressed): 3.3 MB
Character Set: UTF8MB4
Export Compatibility: MySQL 5.7+, MariaDB 10.2+

Docker Deployment

Success Rate: 83% (5/6 services operational)
Build Time: 2.8 minutes (all services)
Startup Time: 12 seconds
Total Memory: 770 MB
Total Disk: ~2.5 GB

Asset Library

Total Size: 695 MB
Catalogue Icons: 5,655 files
Achievement Images: 2,080 files
Sound Files: 806 samples
Badge Parts: 242 files

📞 Support & Resources

Documentation

DOCKER_README.md - Docker deployment guide
DOCKER_TEST_REPORT.md - Testing documentation
DOCKER_FIXES_SUMMARY.md - Applied fixes
database_backup/MIGRATION_GUIDE.txt - Database migration

Useful Commands Reference

# Start services
docker-compose up -d

# Stop services
docker-compose down

# View logs
docker-compose logs -f [service]

# Restart service
docker-compose restart [service]

# Execute command in container
docker-compose exec [service] [command]

# View running processes
docker-compose ps

# View resource usage
docker stats

# Create backup
./docker-backup.sh

# Verify setup
./verify-docker-setup.sh

Common Operations

Access MySQL:

docker-compose exec mysql mysql -u habbo_user -phabbo_password_2024 habbo_retro

View Emulator Console:

docker-compose logs -f emulator

Restart Services After Config Change:

docker-compose restart emulator
docker-compose restart cool-ui

Update Docker Images:

docker-compose pull
docker-compose up -d

🎯 Quick Reference

Service Status

docker-compose ps

Access URLs

Database Access

# Docker
mysql -h localhost -P 3307 -u habbo_user -phabbo_password_2024 habbo_retro

# Local
mysql -h localhost -u habbo_user -phabbo_password_2024 habbo_retro

Log Files

# All logs
docker-compose logs -f

# Specific service
docker-compose logs -f emulator
docker-compose logs -f mysql

📝 License & Credits

Emulator

Arcturus Morningstar - Open-source Habbo emulator
Repository: https://git.krews.org/morningstar/Arcturus-Community
License: Educational purposes

Clients

Nitro React - React-based Habbo client
Cool UI - Modern Habbo client interface

CMS

AtomCMS - Laravel-based hotel management

Catalog Translation

Automated translation: MyMemory API
Manual translation: Google Gemini
Translation date: December 6, 2025

🎮 Enjoy Your Habbo Retro!

Your fully containerized Habbo retro hotel is ready to use!

Quick Start: Run ./docker-start.sh and visit http://localhost:5174

For questions, issues, or contributions, check the documentation files in this repository.

Last Updated: December 6, 2025 Version: 1.0.0 Database Version: 20251206_155812

README.md

Habbo Retro - Complete Setup Guide

📋 Table of Contents

🎮 Project Overview

Key Statistics

📦 What's Included

Core Components

Catalog Translation Status

🗄️ Database Information

Connection Details

Database Structure

Quick Database Queries

🚀 Quick Start

Prerequisites

Option 1: Using Helper Scripts (Recommended)

Option 2: Using Docker Compose Directly

First Time Setup

🌐 Service URLs

Client Access

Server Connections

Useful Endpoints

🔐 Default Login Credentials

MySQL Database

Hotel Users

AtomCMS Admin

🐳 Docker Services

Service Details

1. MySQL Database

2. Arcturus Emulator

3. Asset Server

4. Cool UI (Primary Client)

5. Nitro React (Alternative Client)

6. AtomCMS

Resource Usage Summary

📁 File Structure

💾 Database Backup & Migration

Location of Database Dump

Database Backup Details

Creating New Backups

Restoring from Backup

Migrating to New Server

🔧 Development

Running Services Locally (Non-Docker)

MySQL Database

Arcturus Emulator

Cool UI

Nitro React

Asset Server

AtomCMS

Configuration Files

Building Docker Images

🔍 Troubleshooting

Services Won't Start

Emulator Can't Connect to Database

Client Shows Blank Page

Database Import Fails

CMS Shows 500 Error

Port Already in Use

Reset Everything

🚀 Production Deployment

Pre-Deployment Checklist

Security Recommendations

Performance Optimization

Monitoring

📊 Project Statistics

Translation Achievement

Database Metrics

Docker Deployment

Asset Library

📞 Support & Resources

Documentation

Useful Commands Reference

Common Operations

🎯 Quick Reference

Service Status

Access URLs

Database Access

Log Files

📝 License & Credits

Emulator