Component	Requirement
PHP	8.1 or higher
Database	MariaDB 10.6+ or MySQL 8.0+
Web Server	Apache (mod_rewrite) or Nginx
Node.js	20 or higher
Yarn	1.22+ or 4.x (Berry)
Composer	2.x

Installation

Linux (Ubuntu / Debian)

# 1. System dependencies
sudo apt update
sudo apt install -y git curl wget unzip nginx mariadb-server \
  php8.3 php8.3-cli php8.3-fpm php8.3-mysql php8.3-xml \
  php8.3-mbstring php8.3-curl php8.3-zip php8.3-bcmath \
  php8.3-gd php8.3-sockets php8.3-intl

# 2. Install Composer
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# 3. Install Node.js & Yarn
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
sudo corepack enable
corepack install -g yarn@latest

# 4. Clone the project
git clone https://gitlab.epicnabbo.nl/RemcoEpic/atomcms-edit.git /var/www/atomcms
cd /var/www/atomcms

# 5. Configure environment
cp .env.example .env
php artisan key:generate
# Edit .env with your database credentials:
#   DB_DATABASE=habbo
#   DB_USERNAME=root
#   DB_PASSWORD=yourpassword

# 6. Install PHP dependencies
composer install --no-dev --optimize-autoloader

# 7. Install frontend dependencies
yarn install

# 8. Create database
mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS habbo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 9. Run migrations & seeders (or use the auto-repair tool)
php artisan migrate --seed
# Or use the interactive repair tool:
# php artisan atom:check --fix

# 10. Build frontend assets
yarn build:all

# 11. Set permissions
sudo chown -R www-data:www-data storage bootstrap/cache public/build
sudo chmod -R 775 storage bootstrap/cache

# 12. Configure web server

# --- Nginx ---
sudo nano /etc/nginx/sites-available/atomcms

server { listen 80; server_name your-domain.com; root /var/www/atomcms/public;

add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";

index index.php;

charset utf-8;

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

location = /favicon.ico { access_log off; log_not_found off; }
location = /robots.txt  { access_log off; log_not_found off; }

error_page 404 /index.php;

location ~ \.php$ {
    fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

location ~ /\.(?!well-known).* {
    deny all;
}

}

```bash
sudo ln -sf /etc/nginx/sites-available/atomcms /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

# --- Apache ---
sudo a2enmod rewrite
sudo nano /etc/apache2/sites-available/atomcms.conf

<VirtualHost *:80> ServerName your-domain.com DocumentRoot /var/www/atomcms/public

<Directory /var/www/atomcms/public>
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

ErrorLog ${APACHE_LOG_DIR}/atomcms-error.log
CustomLog ${APACHE_LOG_DIR}/atomcms-access.log combined

``` ```bash sudo a2ensite atomcms sudo systemctl reload apache2 ```

13. Restart PHP-FPM to clear opcache

sudo systemctl restart php8.3-fpm

14. Visit http://your-domain.com in your browser


---

### Windows (XAMPP / WampServer)

#### Prerequisites
- [XAMPP](https://www.apachefriends.org/) (PHP 8.1+, Apache, MariaDB) or [WampServer](https://www.wampserver.com/)
- [Node.js](https://nodejs.org/) (20 LTS or higher)
- [Yarn](https://yarnpkg.com/getting-started/install) (`npm install -g yarn` after Node.js)
- [Composer](https://getcomposer.org/download/) (Windows installer)
- [Git for Windows](https://git-scm.com/download/win)

#### Steps

```powershell
# 1. Open PowerShell or CMD as Administrator

# 2. Clone the project
git clone https://gitlab.epicnabbo.nl/RemcoEpic/atomcms-edit.git C:\xampp\htdocs\atomcms
cd C:\xampp\htdocs\atomcms

# 3. Configure environment
copy .env.example .env
php artisan key:generate

# Edit .env with your XAMPP database credentials:
#   DB_CONNECTION=mariadb
#   DB_HOST=localhost
#   DB_PORT=3306
#   DB_DATABASE=habbo
#   DB_USERNAME=root
#   DB_PASSWORD=

# 4. Start XAMPP services
# Open XAMPP Control Panel → Start Apache & MySQL

# 5. Create database
# Open phpMyAdmin (http://localhost/phpmyadmin)
# → New → Database name: habbo → Charset: utf8mb4_unicode_ci → Create

# 6. Install PHP dependencies
composer install --no-dev --optimize-autoloader

# 7. Install frontend dependencies
yarn install

# 8. Run migrations & seeders
php artisan migrate --seed
# Or use the interactive repair tool:
# php artisan atom:check --fix

# 9. Build frontend assets
yarn build:all

# 10. Set permissions (required for storage & cache)
# Right-click storage\ and bootstrap\cache\ folders
# → Properties → Security → Edit → Add "Everyone" → Full Control
# Or run in PowerShell as Admin:
icacls storage /grant Everyone:F /T
icacls bootstrap/cache /grant Everyone:F /T
icacls public/build /grant Everyone:F /T

# 11. Enable Apache mod_rewrite
# Open XAMPP Control Panel → Apache → Config → httpd.conf
# Uncomment: LoadModule rewrite_module modules/mod_rewrite.so

# 12. Visit http://localhost/atomcms/public in your browser

Note: If you use IIS on Windows, the repair tool supports auto-detection: php artisan atom:check --fix

Quick Start (Repair Tool)

# Interactive mode (asks for confirmation before each step)
php artisan atom:check --fix

# Auto mode (fixes everything automatically without asking)
php artisan atom:check --auto

# Force platform detection
php artisan atom:check --platform=nginx

# Dutch language output
php artisan atom:check --fix --lang=nl

Commands

# Check only (no changes)
php artisan atom:check

# Interactive fix (asks before each step)
php artisan atom:check --fix

# Automatic fix (no questions)
php artisan atom:check --auto

# Fix gamedata symlinks for bundled assets
php artisan atom:fix-gamedata-symlinks

# Preview symlinks (dry-run)
php artisan atom:fix-gamedata-symlinks --dry-run

Yarn Scripts

# Build all themes
yarn build:all

# Build single theme
yarn build:atom      # Atom theme
yarn build:dusk      # Dusk theme

# Development
yarn dev             # Start Vite dev server
yarn dev:atom        # Dev server for Atom theme

# Linting & Formatting
yarn lint            # Check JS/Vue
yarn lint:fix        # Fix JS/Vue
yarn lint:css        # Check CSS
yarn lint:css:fix    # Fix CSS
yarn format          # Format everything
yarn format:check    # Check formatting

# Full check
yarn check           # Lint + format check
yarn check:php       # PHP syntax check
yarn check:security  # Composer & npm audit
yarn check:deps      # Check outdated packages

# Cache
yarn clean           # Clear Vite cache
yarn rebuild         # Clean + install + build

PHP Commands

# Auto-fix code style
php artisan atom:fix-code

# Static analysis (PHPStan Level 3)
./vendor/bin/phpstan analyse

# Build frontend assets
yarn build:atom
yarn build:dusk

# Development mode
yarn dev:atom

Repair Tool Details

The atom:check command performs over 100 deep system checks and offers to fix them automatically.

Diagnostic Checks

Section	What it Checks
Environment	.env, APP_KEY, Debug mode, Composer security
Database	Tables, columns, migrations, seeders, settings, radio, admin
PHP Stack	Extensions, php.ini, config cache, session
Web Server	Apache/Nginx/IIS config, SSL
System	Permissions, firewall ports
Assets	Frontend, Redis, Cron, Queue, Supervisor, Vite
HTTP Errors	400, 401, 403, 404, 419, 429, 500, 502, 503, 504

Auto-Fix Steps

Step	Action
1	Environment (.env, APP_KEY)
2	Clear all caches
3	Fix permissions
4	Run migrations
5	Run seeders
6	Fix storage (symlink, directories)
6b	Fix Radio tables
7	Fix Gamedata symlinks
8	Create admin user
9	Web server config (.htaccess)
10	PHP config & extensions
11	Build assets (npm)
12	Fix HTTP errors

Auto-detects: Linux, Windows IIS, XAMPP, WAMP, Apache, Nginx

Performance Optimizations

Optimization	Description
Vite 8	Fastest build tool
esbuild	Faster minification
Better chunking	Optimal code splitting
Gzip + Brotli	Compression (~70% smaller)
Resource hints	DNS prefetch, preconnect, preload
HTTP/2	Faster network requests
Console removed	Smaller JS bundles
Caching	Vite cache + optimizedeps

Gamedata Symlinks

The atom:fix-gamedata-symlinks command creates symlinks in the Gamedata directory to point to optimized bundled assets, significantly improving game client load times.

Symlink	Target	Purpose
`effect`	`bundled/effect`	Avatar effects
`furniture`	`bundled/furniture`	Furniture assets
`generic`	`bundled/generic`	Generic assets
`pet`	`bundled/pet`	Pet assets
`figure`	`bundled/figure`	Avatar figures
`generic_custom`	`bundled/generic`	Custom generic

Tech Stack

Backend: Laravel 13
Frontend: React 19 + Alpine.js
Build: Vite 8
CSS: TailwindCSS 4
Admin Panel: Filament 5
Database: MariaDB / MySQL
Linting: ESLint + Stylelint + Prettier

Credits

Remco (Epicnabbo) — Core Maintainer, System Architecture
Kasja — Design & Themes
Kani — RCON & API
Atom Community — Testing & Feedback

Made with love for the Retro Community

Languages

PHP 58.5%

Blade 30.2%

JavaScript 7.6%

CSS 3%

Shell 0.6%

Other 0.1%