smueller/HexaHost-Panel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add README and DEPLOY documentation for HexaHost Panel.

Browse Source 
Replace default Laravel README with project overview and link detailed Plesk deployment steps.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
TheOnlyMace
2026-05-17 13:30:07 +02:00
parent 75299b723d
commit 5b260022f8
2 changed files with 473 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

323
DEPLOY.md Normal file
View File

@@ -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=<sicher>
```
---
## 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=<plesk-domain-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
```
`<plesk-domain-user>` 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=<langes-zufallssecret>
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=<plesk-domain-user>
WorkingDirectory=/var/www/vhosts/panel.hexahost.de/panel-app
Environment=CONSOLE_PROXY_PORT=6090
Environment=CONSOLE_PROXY_SECRET=<gleich wie .env>
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
```

188
README.md
View File

@@ -1,58 +1,170 @@
<p align="center"><a href="https://laravel.com" target="_blank"><img src="https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg" width="400" alt="Laravel Logo"></a></p>
# HexaHost Panel
<p align="center">
<a href="https://github.com/laravel/framework/actions"><img src="https://github.com/laravel/framework/workflows/tests/badge.svg" alt="Build Status"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/dt/laravel/framework" alt="Total Downloads"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/v/laravel/framework" alt="Latest Stable Version"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/l/laravel/framework" alt="License"></a>
</p>
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`.