From 5b260022f8e7025b862239c6b8bfa2bda2a97c2d Mon Sep 17 00:00:00 2001 From: TheOnlyMace <0815cracky@gmail.com> Date: Sun, 17 May 2026 13:30:07 +0200 Subject: [PATCH] Add README and DEPLOY documentation for HexaHost Panel. Replace default Laravel README with project overview and link detailed Plesk deployment steps. Co-authored-by: Cursor --- DEPLOY.md | 323 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 188 ++++++++++++++++++++++++------- 2 files changed, 473 insertions(+), 38 deletions(-) create mode 100644 DEPLOY.md diff --git a/DEPLOY.md b/DEPLOY.md new file mode 100644 index 0000000..a50d6f8 --- /dev/null +++ b/DEPLOY.md @@ -0,0 +1,323 @@ +# Deployment auf Plesk – HexaHost Panel + +Anleitung für **panel.hexahost.de** auf Plesk mit PHP 8.3+, MariaDB, Queue-Worker und Scheduler. + +--- + +## Übersicht + +| Komponente | Pflicht | Hinweis | +|------------|---------|---------| +| Document Root → `public/` | Ja | Nicht Projektroot | +| `composer install --no-dev` | Ja | Auf dem Server | +| `npm run build` | Ja | `public/build/` ist nicht im Git | +| MariaDB | Ja (Prod.) | Session, Cache, Queue, Daten | +| Cron `schedule:run` | Ja | Jede Minute | +| Queue-Worker | Ja | WHMCS-Provisioning | +| Traefik-Pfad beschreibbar | Bei Traefik-VMs | Oder Sync von anderem Host | +| Console-Proxy | Optional | Empfohlen für VNC | + +--- + +## 1. Domain & PHP (Plesk) + +1. Domain **panel.hexahost.de** anlegen. +2. **Document Root** auf das `public`-Verzeichnis der App setzen, z. B.: + ``` + /var/www/vhosts/panel.hexahost.de/panel-app/public + ``` +3. **PHP 8.3 oder 8.4** aktivieren. +4. Extensions: `pdo_mysql`, `mbstring`, `openssl`, `curl`, `fileinfo`, `zip`, `bcmath`. +5. **Let’s Encrypt** für HTTPS aktivieren. + +PHP-Binary notieren (für Cron/Worker), z. B.: +```text +/opt/plesk/php/8.3/bin/php +``` + +--- + +## 2. MariaDB (Plesk) + +1. Datenbank anlegen: `hexahost_panel` +2. Benutzer `panel_user` mit vollen Rechten auf diese DB. +3. In `.env`: + +```env +APP_ENV=production +APP_DEBUG=false +APP_URL=https://panel.hexahost.de + +DB_CONNECTION=mariadb +DB_HOST=localhost +DB_PORT=3306 +DB_DATABASE=hexahost_panel +DB_USERNAME=panel_user +DB_PASSWORD= +``` + +--- + +## 3. Code deployen + +### Per Git (empfohlen) + +```bash +cd /var/www/vhosts/panel.hexahost.de +git clone ssh://git@git.hexahost.dev:8006/smueller/HexaHost-Panel.git panel-app +cd panel-app +``` + +Plesk *Git*-Extension: Repository verknüpfen, Deploy-Pfad `panel-app`, Document Root auf `panel-app/public` zeigen. + +### Nicht deployen + +- `vendor/`, `node_modules/`, `.env` +- `database/database.sqlite` (nur lokal) + +--- + +## 4. Installation (SSH) + +Als **Domain-Systembenutzer** (nicht root, sofern möglich): + +```bash +cd /var/www/vhosts/panel.hexahost.de/panel-app + +composer install --no-dev --optimize-autoloader + +npm ci +npm run build + +cp .env.example .env +nano .env # alle Werte für Produktion setzen + +php artisan key:generate +php artisan migrate --force +php artisan db:seed --class=HostingSeeder --force # nur beim Erst-Setup + +chmod -R ug+rwx storage bootstrap/cache + +php artisan config:cache +php artisan route:cache +php artisan view:cache +``` + +### `.env` Produktions-Checkliste + +- [ ] `PROXMOX_TOKEN` gesetzt (API-Token, nicht Root-Passwort) +- [ ] `PLESK_URL`, `PLESK_USER`, `PLESK_PASS` +- [ ] `WHMCS_API_SECRET` (stark, identisch in WHMCS-Modul) +- [ ] `WHMCS_ALLOWED_IPS` = WHMCS-Server-IP +- [ ] `TRAEFIK_PUBLIC_IP`, `TRAEFIK_DYNAMIC_CONFIG_PATH`, `TRAEFIK_RELOAD_COMMAND` +- [ ] Netzwerk: `HOSTING_GATEWAY=10.32.0.1`, `HOSTING_PUBLIC_GATEWAY=185.45.149.241`, `HOSTING_PUBLIC_CIDR=28` +- [ ] Admin-2FA: `ADMIN_2FA_REQUIRED=true` + +Nach Seeder: Admin-Passwort ändern, 2FA einrichten. + +--- + +## 5. Scheduler (Cron in Plesk) + +**Websites & Domains → panel.hexahost.de → Geplante Aufgaben** + +| Feld | Wert | +|------|------| +| Befehl | `/opt/plesk/php/8.3/bin/php /var/www/vhosts/panel.hexahost.de/panel-app/artisan schedule:run` | +| Intervall | **Jede Minute** | + +Läuft u. a.: VMID-Freigabe, ISO-Purge, Snapshot-Prune, Metriken. + +--- + +## 6. Queue-Worker (Pflicht) + +Ohne Worker bleiben WHMCS-Bestellungen in `jobs` hängen. + +### systemd (empfohlen) + +Datei `/etc/systemd/system/hexahost-queue.service`: + +```ini +[Unit] +Description=HexaHost Panel Queue Worker +After=network.target mariadb.service + +[Service] +Type=simple +User= +Group=psacln +WorkingDirectory=/var/www/vhosts/panel.hexahost.de/panel-app +ExecStart=/opt/plesk/php/8.3/bin/php artisan queue:work database --sleep=3 --tries=3 --max-time=3600 +Restart=always +RestartSec=5 +StandardOutput=append:/var/www/vhosts/panel.hexahost.de/panel-app/storage/logs/queue.log +StandardError=append:/var/www/vhosts/panel.hexahost.de/panel-app/storage/logs/queue.log + +[Install] +WantedBy=multi-user.target +``` + +```bash +systemctl daemon-reload +systemctl enable --now hexahost-queue +systemctl status hexahost-queue +``` + +`` z. B. mit `ls -la /var/www/vhosts/panel.hexahost.de` ermitteln. + +### Notlösung (nur wenig Traffic) + +Cron jede Minute: +```bash +php artisan queue:work database --stop-when-empty --max-time=55 +``` + +--- + +## 7. Traefik + +Das Panel schreibt Kunden-Routen nach `TRAEFIK_DYNAMIC_CONFIG_PATH` und führt `TRAEFIK_RELOAD_COMMAND` aus. + +**Voraussetzungen:** + +- Panel-Prozess (PHP-FPM-User) darf die YAML-Datei **schreiben** +- Reload-Befehl ist ausführbar (ggf. `sudoers` für `docker exec …`) + +**Traefik auf anderem Server:** Pfad muss per NFS/SSH/rsync erreichbar sein – reines Plesk-Upload reicht dann nicht. + +Beispiel `.env`: +```env +TRAEFIK_DYNAMIC_CONFIG_PATH=/etc/traefik/dynamic/customers.yaml +TRAEFIK_RELOAD_COMMAND="docker exec traefik kill -HUP 1" +TRAEFIK_PUBLIC_IP=185.45.149.98 +``` + +--- + +## 8. Console-WebSocket-Proxy (optional) + +### `.env` +```env +CONSOLE_PROXY_ENABLED=true +CONSOLE_PROXY_WS_URL=wss://panel.hexahost.de/ws/vm +CONSOLE_PROXY_SECRET= +CONSOLE_PROXY_VALIDATE_URL=https://panel.hexahost.de/api/console/validate +``` + +### Node-Abhängigkeit +```bash +cd panel-app +npm install ws +``` + +### systemd für Proxy + +`/etc/systemd/system/hexahost-console-proxy.service`: + +```ini +[Unit] +Description=HexaHost VNC WebSocket Proxy +After=network.target + +[Service] +User= +WorkingDirectory=/var/www/vhosts/panel.hexahost.de/panel-app +Environment=CONSOLE_PROXY_PORT=6090 +Environment=CONSOLE_PROXY_SECRET= +Environment=CONSOLE_PROXY_VALIDATE_URL=https://panel.hexahost.de/api/console/validate +ExecStart=/usr/bin/node scripts/console-ws-proxy.mjs +Restart=always + +[Install] +WantedBy=multi-user.target +``` + +### nginx (Plesk – zusätzliche nginx-Direktive) + +```nginx +location /ws/vm/ { + proxy_pass http://127.0.0.1:6090; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header Host $host; + proxy_read_timeout 86400; +} +``` + +--- + +## 9. Firewall / Netzwerk + +| Quelle | Ziel | Port | +|--------|------|------| +| Panel-Server | Proxmox (hyperion) | 8006/tcp | +| WHMCS-Server | panel.hexahost.de | 443/tcp | +| Panel-Server | Plesk API | 8443/tcp | + +--- + +## 10. WHMCS-Modul + +1. `whmcs-module/hexahost/` nach `modules/servers/hexahost/` in WHMCS kopieren. +2. Server in WHMCS anlegen: API-URL `https://panel.hexahost.de/api/whmcs` +3. `WHMCS_API_SECRET` identisch mit Panel-`.env`. + +--- + +## 11. Updates deployen + +```bash +cd /var/www/vhosts/panel.hexahost.de/panel-app + +php artisan down # optional + +git pull +composer install --no-dev --optimize-autoloader +npm ci && npm run build +php artisan migrate --force +php artisan config:cache +php artisan route:cache +php artisan view:cache +php artisan queue:restart + +php artisan up +``` + +--- + +## 12. Abnahme-Tests + +| Test | Erwartung | +|------|-----------| +| `GET /login` | 200, HexaHost-UI | +| Admin-Login + 2FA | Dashboard | +| VM-Liste / Status | Proxmox erreichbar | +| Manuelle VM / WHMCS-Order | Job verarbeitet, Status `active` | +| Traefik-VM | DNS + YAML + Reload | +| `storage/logs/laravel.log` | keine wiederholten Errors | +| `systemctl status hexahost-queue` | active (running) | + +--- + +## Fehlerbehebung + +| Symptom | Lösung | +|---------|--------| +| 500 nach Deploy | `storage/` Rechte, `php artisan config:clear`, Log prüfen | +| Provisioning hängt | Queue-Worker läuft? `jobs`-Tabelle prüfen | +| Keine Traefik-Route | Pfad/Rechte/Reload-Befehl | +| WHMCS 403 | `WHMCS_API_SECRET`, Uhrzeit (Replay), `WHMCS_ALLOWED_IPS` | +| Konsole verbindet nicht | Proxy + nginx WebSocket, VM läuft | +| Assets fehlen | `npm run build` auf Server | + +--- + +## Support-Logs + +```bash +tail -f storage/logs/laravel.log +tail -f storage/logs/queue.log # falls konfiguriert +php artisan queue:failed +``` diff --git a/README.md b/README.md index 5ad1377..4d67685 100644 --- a/README.md +++ b/README.md @@ -1,58 +1,170 @@ -

Laravel Logo

+# HexaHost Panel -

-Build Status -Total Downloads -Latest Stable Version -License -

+Web-Panel zur Steuerung von **Proxmox VE**-VMs, **Traefik**-Routen (File Provider), **Plesk DNS** und Anbindung an **WHMCS 9** für Bestellung und Abrechnung. -## About Laravel +**Repository:** `ssh://git@git.hexahost.dev:8006/smueller/HexaHost-Panel.git` -Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as: +Produktions-URL (Ziel): [https://panel.hexahost.de](https://panel.hexahost.de) -- [Simple, fast routing engine](https://laravel.com/docs/routing). -- [Powerful dependency injection container](https://laravel.com/docs/container). -- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage. -- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent). -- Database agnostic [schema migrations](https://laravel.com/docs/migrations). -- [Robust background job processing](https://laravel.com/docs/queues). -- [Real-time event broadcasting](https://laravel.com/docs/broadcasting). +Ausführliche Server-Anleitung: [DEPLOY.md](DEPLOY.md) -Laravel is accessible, powerful, and provides tools required for large, robust applications. +--- -## Learning Laravel +## Funktionen -Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. +| Bereich | Beschreibung | +|--------|----------------| +| **VM-Verwaltung** | Anlegen, Start/Stop/Reboot, Live-Status, Konsole (noVNC) | +| **Provisioning** | Queue-basiert mit Rollback (Proxmox → DNS → Traefik) | +| **WHMCS API** | HMAC-gesicherte Endpoints: Provision, Suspend, Terminate, Status | +| **Netzwerk** | Private IP-Pools (10.32.0.0/24), optionale öffentliche IPs | +| **Traefik** | YAML-Merge, atomisches Schreiben, Reload | +| **Snapshots** | Manuell + automatisch vor kritischen Aktionen, 48h Retention | +| **ISO-Upload** | Kunden-ISO auf Proxmox-Storage (Limits konfigurierbar) | +| **Backups** | vzdump → PBS (wenn `BACKUPS_ENABLED=true`) | +| **Firewall** | Regeln pro VM, Sync zu Proxmox | +| **Sicherheit** | 2FA-Pflicht für Admins, Login-Throttle, Policies pro Rolle | +| **Admin** | VM-Templates, System-Health, Benutzer, IP-Pools | -In addition, [Laracasts](https://laracasts.com) contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library. +--- -You can also watch bite-sized lessons with real-world projects on [Laravel Learn](https://laravel.com/learn), where you will be guided through building a Laravel application from scratch while learning PHP fundamentals. +## Architektur -## Agentic Development - -Laravel's predictable structure and conventions make it ideal for AI coding agents like Claude Code, Cursor, and GitHub Copilot. Install [Laravel Boost](https://laravel.com/docs/ai) to supercharge your AI workflow: - -```bash -composer require laravel/boost --dev - -php artisan boost:install +``` +WHMCS 9 ──HMAC API──► Laravel Panel ──► Proxmox VE (Hyperion) + ├──► Plesk DNS (A-Records) + └──► Traefik dynamic YAML + Reload ``` -Boost provides your agent 15+ tools and skills that help agents build Laravel applications while following best practices. +--- -## Contributing +## Tech-Stack -Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions). +- **PHP** 8.3+, **Laravel** 13 +- **SQLite** (Entwicklung) / **MariaDB** (Produktion empfohlen) +- **Tailwind CSS 4**, **Vite** +- **Queue:** `database` (Worker erforderlich) +- **WHMCS-Modul:** `whmcs-module/hexahost/` -## Code of Conduct +--- -In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct). +## Lokale Entwicklung -## Security Vulnerabilities +### Voraussetzungen -If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed. +- PHP 8.3+, Composer, Node.js 20+ +- Optional: Proxmox API-Token in `.env` -## License +### Installation -The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). +```bash +git clone ssh://git@git.hexahost.dev:8006/smueller/HexaHost-Panel.git +cd HexaHost-Panel + +composer install +cp .env.example .env +php artisan key:generate +php artisan migrate +php artisan db:seed --class=HostingSeeder + +npm install +npm run build +``` + +### Starten + +```bash +# Terminal 1 – App +php artisan serve + +# Terminal 2 – Queue (Provisioning) +php artisan queue:work + +# Terminal 3 – optional Assets +npm run dev +``` + +Standard-Admin nach Seeder: `admin@hexahost.local` / `admin1234` — **in Produktion sofort ändern.** + +### Tests + +```bash +npm run build +php artisan test +``` + +--- + +## Konfiguration + +Alle hosting-spezifischen Werte liegen in `config/hosting.php` und werden über `.env` gesetzt. Vorlage: `.env.example`. + +Wichtige Gruppen: + +| Präfix | Zweck | +|--------|--------| +| `PROXMOX_*` | API, Node, Storage, ISO, PBS | +| `HOSTING_*` / `HOSTING_PUBLIC_*` | IP-Pools, Gateways, CIDR | +| `TRAEFIK_*` | Pfad zur dynamic config, Reload | +| `PLESK_*` | DNS-API | +| `WHMCS_*` | API-Secret, IP-Allowlist | +| `CONSOLE_PROXY_*` | WebSocket-Proxy (optional) | + +**Niemals** `.env` committen (enthält Secrets). + +--- + +## Geplante Aufgaben (Cron) + +Der Laravel Scheduler muss **jede Minute** laufen (`php artisan schedule:run`): + +| Command | Intervall | +|---------|-----------| +| `hosting:release-vmids` | alle 15 Min. | +| `hosting:purge-iso-uploads` | stündlich | +| `hosting:prune-snapshots` | stündlich | +| `hosting:collect-metrics` | alle 5 Min. | + +--- + +## WHMCS + +Server-Modul-Skeleton: `whmcs-module/hexahost/hexahost.php` + +API-Basis: `https://panel.hexahost.de/api/whmcs/` (nur HMAC, kein offenes Hosting-API mehr). + +`WHMCS_API_SECRET` in Panel-`.env` und im WHMCS-Modul identisch setzen. + +--- + +## Console-Proxy (optional) + +Direkte Browser-Verbindung zu Proxmox-VNC ist unsicher und oft blockiert. Empfohlen: + +1. `CONSOLE_PROXY_ENABLED=true` in `.env` +2. Node-Proxy starten: `scripts/console-ws-proxy.mjs` +3. Reverse-Proxy `/ws/vm` → lokaler Port (siehe [DEPLOY.md](DEPLOY.md)) + +--- + +## Projektstruktur (Auszug) + +``` +app/Services/Hosting/ + Proxmox/ # API-Client, VM-Management + Provisioning/ # Provision, Deprovision, IP, VMID + Traefik/ # YAML-Generator + Plesk/ # DNS + Snapshots/ # Snapshot-Service + ... +routes/ + web.php # Panel-UI + api.php # WHMCS + Console-Validate +whmcs-module/ # WHMCS 9 Server Module +``` + +--- + +## Lizenz + +MIT (Laravel-Basis). Siehe `composer.json`.