Ship async-ops foundation + 9 major features + local Docker dev harness

.env.example

@@ -28,6 +28,18 @@ DB_DATABASE=laranode
 DB_USERNAME=laranode
 DB_PASSWORD=
 
+MYSQL_ADMIN_HOST=127.0.0.1
+MYSQL_ADMIN_PORT=3306
+MYSQL_ADMIN_DB=mysql
+MYSQL_ADMIN_USERNAME=
+MYSQL_ADMIN_PASSWORD=
+
+PGSQL_HOST=127.0.0.1
+PGSQL_PORT=5432
+PGSQL_DB=postgres
+PGSQL_USERNAME=postgres
+PGSQL_PASSWORD=
+
 SESSION_DRIVER=database
 SESSION_LIFETIME=120
 SESSION_ENCRYPT=false

.gitignore

@@ -25,3 +25,11 @@ yarn-error.log
 package-lock.json
 *.DS_Store*
 *.php-cs-fixer.cache*
+/test-results
+/playwright-report
+/.playwright-mcp
+/dark-*.jpeg
+/graphs-dark.jpeg
+/notif-dark-fixed.jpeg
+/pie-fixed.jpeg
+.env.local-backup

CLAUDE.md

@@ -0,0 +1,106 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Laranode is a self-hosted server control panel (cPanel/Plesk alternative) built on Laravel 12 + Inertia 2 + React 18. It manages the **host machine itself** — Apache vhosts, per-site PHP-FPM pools, MySQL databases, Let's Encrypt SSL, UFW firewall, a web file manager, and live system stats. Target host is Ubuntu 24.04+; the panel is deployed at `/home/laranode_ln/panel`.
+
+## Local dev/test (Docker)
+
+`local-dev/` provides a single systemd-enabled Ubuntu 24.04 container ("VPS-in-a-box") with the full Laranode stack (Apache, PHP-FPM, MySQL, Reverb, queue worker). No real Linux VPS needed for integration testing.
+
+Key targets (run from repo root):
+- `make up` — build image + start container + run entrypoint provisioning
+- `make verify` — check all services running + HTTP panel response
+- `make test` — run Pest suite inside container
+- `make test-system` — Pest with `LARANODE_SYSTEM_TESTS=1` (exercises sudo scripts)
+- `make ssl-test` — bring up Pebble ACME sidecars (pebble + challtestsrv) + test SSL issuance
+- `make nuke` — destroy container + all named volumes (full reset)
+
+Admin login: `admin@laranode.test` / `password`
+
+> **Windows:** Run `make` and `docker compose` from **PowerShell or cmd**, NOT Git Bash.
+> Git Bash (MSYS) breaks docker two ways: it strips the Windows environment that
+> `docker.exe` needs to locate its compose plugin, and it rewrites in-container paths
+> (`/home/…`, `/opt/…`) passed to `docker exec` into `C:/msys64/…`, which breaks the
+> provisioning recipes. The Makefile's `MSYS_*` exports fix the path rewriting, but the
+> plugin-discovery failure remains — so use PowerShell/cmd. Plain `docker exec
+> laranode-lab …` works from any shell.
+
+## Commands
+
+```bash
+composer dev          # all-in-one dev: php artisan serve + queue:listen + pail (logs) + vite, concurrently
+npm run dev           # vite only
+npm run build         # production asset build
+php artisan reverb:start   # websocket server — NOT started by `composer dev`; needed for live stats
+./vendor/bin/pest                       # run tests (Pest 3)
+./vendor/bin/pest --filter="text"       # single test by name
+php artisan test --filter=AccountsTest  # alt runner, by file/test
+./vendor/bin/pint     # format (Laravel Pint) — run before committing PHP
+php artisan migrate
+php artisan laranode:create-admin   # interactive admin creation (username is forced to "laranode")
+```
+
+Tests use Pest with `RefreshDatabase` (see `tests/Pest.php`); feature tests live in `tests/Feature/<Domain>/`.
+
+## Verify every feature before calling it done
+
+After implementing ANY feature or bug fix, run this gate before declaring it complete (and before committing):
+
+1. **Backend tests** — `./vendor/bin/pest` (or `--filter` for the touched domain, then the full suite to catch regressions).
+2. **Frontend tests** — `npx vitest run` for the touched component, then the full Vitest suite.
+3. **Build assets** — `npm run build` (the lab serves `public/build/`, not Vite dev — stale assets are why a change "doesn't show"). Clear caches if a blade/route changed: `php artisan optimize:clear`.
+4. **Playwright check** — drive the running panel (lab container, admin `admin@laranode.test` / `password`) to confirm the change actually works in the real app and toggle dark mode on the affected page(s). Verify against the live result, not just the diff.
+
+Run all four in the lab container, e.g. `docker exec laranode-lab bash -lc 'cd /home/laranode_ln/panel && <cmd>'`.
+
+**Pint scope:** only format files you changed (`./vendor/bin/pint <file> ...`). NEVER run `pint app/` or a whole-tree pint — it sweeps dozens of pre-existing unformatted files into your diff.
+
+## Environment caveat
+
+System-touching features (sudo scripts, `systemctl`, `/proc`, `certbot`, `ufw`) only run on a real Linux host. On Windows/macOS dev machines those `Process` calls fail — exercise that behavior on a Linux VPS, not locally. DB is MySQL in prod (`.env.example`).
+
+## Architecture
+
+### Request layering
+Controllers are thin. The pattern is: **Controller → FormRequest (validation) → Service or Action (work)**.
+
+- `app/Services/<Domain>/` — orchestration, usually wrapping system calls (`Websites`, `MySQL`, `Accounts`, `Dashboard`, and `Laranode` infra helpers). Convention: a single `handle()` method, and a sibling custom `*Exception` class declared in the same file (e.g. `CreateWebsiteException`).
+- `app/Actions/<Domain>/` — single-purpose units (`Filemanager`, `Firewall`, `SSL`, `MySQL`). Filemanager actions receive a Flysystem `Filesystem` injected by `AppServiceProvider`, sandboxed to the authenticated user's homedir (`DISALLOW_LINKS`).
+
+### How the panel touches the system (the core idea)
+Two distinct mechanisms, both via the `Process` facade:
+
+1. **Privileged mutations** shell out to whitelisted bash scripts:
+   ```php
+   Process::run(['sudo', config('laranode.laranode_bin_path') . '/laranode-add-vhost.sh', ...$args]);
+   ```
+   Scripts live in `laranode-scripts/bin/`, config templates (Apache vhost, PHP-FPM pool, systemd units) in `laranode-scripts/templates/`. The installer grants `www-data` NOPASSWD sudo for `laranode-scripts/bin/*.sh`. When adding a privileged op: add a `*.sh` script there and call it through a Service — do not run privileged commands inline.
+2. **Read-only stats** call system tools directly (`top`, `free`, `df`, `systemctl`, `ps`, `certbot`, `/proc/net/dev`) via `Process::run('…')` / `Process::pipe([...])`. See `app/Services/Dashboard/SystemStatsService.php`.
+
+### Identity & path conventions (computed, never stored)
+Used throughout the codebase — accessors on the models, not DB columns (comments note casts were unreliable here):
+- System user = `{username}_ln` (`User::systemUsername`)
+- Home dir = `/home/{username}_ln` (`User::homedir`)
+- Website root = `{homedir}/domains/{url}`; `fullDocumentRoot` = website root + `document_root` (`Website`)
+
+### Auth & multi-tenancy
+- `users.role` is `admin` | `user`. `AdminMiddleware` gates admin-only routes (accounts, firewall, PHP manager, admin dashboard, stats history).
+- Non-admins are scoped to their own rows via the `scopeMine()` query scope on `Website`/`Database`.
+- Admins impersonate users via `lab404/laravel-impersonate`. Shared Inertia props (`HandleInertiaRequests`): `auth.user`, `auth.isImpersonating`, `flash.{success,error}`.
+
+### Live stats over websockets (no polling)
+Reverb-based push, not polling:
+1. React page subscribes to a private channel and whispers a `client-typing` event (`resources/js/Pages/Dashboard/...`).
+2. Server's `MessageReceivedListener` (auto-discovered, hooks `Laravel\Reverb\Events\MessageReceived`) matches the channel and dispatches `SystemStatsEvent` / `TopStatsEvent`.
+3. Those events gather fresh stats in their constructor and broadcast back on private channels `systemstats` / `topstats` — both authorized to admins only (`routes/channels.php`).
+
+Historical stats use sysstat/`sar`: `app/Services/Dashboard/{SarHistory,CPUHistoryService,MemoryHistoryService,NetworkHistoryService}.php`, all implementing `HistoricStatsContract`.
+
+### Frontend
+Inertia + React (JSX, **not** TypeScript). Pages in `resources/js/Pages/<Domain>/`, layouts in `resources/js/Layouts/`. `route()` in JS comes from Ziggy; websockets from Echo/Reverb (`resources/js/echo.js`). Tables use `react-data-table-component`, charts use `chart.js`/`react-chartjs-2`.
+
+### Production runtime
+Apache2 (vhost per site) + per-site PHP-FPM pools + MySQL + certbot (Let's Encrypt, 90-day certs) + UFW. Two systemd services from `laranode-scripts/templates/`: `laranode-reverb.service` (websockets) and `laranode-queue-worker.service` (queue, `QUEUE_CONNECTION=database`). Full provisioning is in `laranode-scripts/bin/laranode-installer.sh`.

README.md

@@ -14,16 +14,28 @@ Laranode is a simple but powerful open-source alternative to cPanel and Plesk, d
 
 ✅ **File Manager** – Built-in (from the ground up) web-based file manager for quick access.  
 
-✅ **Live System Stats** – Monitor CPU, memory, and network usage in real-time. 
+✅ **Live System Stats & Analytics** – Real-time CPU/memory/network monitoring plus historical usage charts and per-user quota tracking.
 
 ✅ **LAMP Stack Administration** – Manage Apache, MySQL, and PHP with ease.  
 
-✅ **User-Friendly Interface** – Clean and simple UI designed for efficiency.  
+✅ **PHP Manager** – Install, update, and remove PHP versions from the web UI.
+
+✅ **Alternative PHP Runtimes** – Switch individual sites between PHP-FPM and FrankenPHP.
+
+✅ **Multi-Engine Database Management** – Create and manage MySQL, MariaDB, and PostgreSQL databases, with per-engine service control (start/stop/restart).
+
+✅ **Automated Backups** – Scheduled or on-demand database and file backups to local disk or S3-compatible storage, with retention and restore.
 
-✅ **MySQL Database Management** – Create and control MySQL databases.  
+✅ **Cron Job Manager** – Create and manage per-user scheduled tasks from the web UI.
+
+✅ **Notifications** – In-app notification center plus email/webhook alerts for operations, SSL expiry, and more.
+
+✅ **Async Operations with Live Progress** – Long-running tasks (SSL issuance, runtime switches, backups) stream real-time progress instead of blocking the request.
 
 ✅ **UFW Firewall** – Manage uncomplicated firewall rules with ease directly from the web interface.  
 
+✅ **User-Friendly Interface** – Clean and simple UI designed for efficiency.  
+
 ## Installation
 
 Laranode can be installed on a FRESH VPS or dedicated server.
@@ -35,8 +47,9 @@ Laranode can be installed on a FRESH VPS or dedicated server.
 - 10GB Disk Space
 
 ### Quick Install
+Run on a clean Ubuntu 24.04 server as root:
 ```bash
-curl -sSL https://raw.githubusercontent.com/crivion/laranode/refs/heads/main/laranode-scripts/bin/laranode-installer.sh | bash
+curl -sSL https://raw.githubusercontent.com/alexandre433/laranode/refs/heads/main/laranode-scripts/bin/laranode-installer.sh | bash
 ```
 
 ## Getting Started
@@ -69,8 +82,13 @@ Login with the credentials provided during installation.
 
 ## Roadmap - Future Release Plans
 
-- 🔹 PHP Manager - install, update, remove PHP versions
-- 🔹 Backup Manager - backup websites, databases, and files
+- 🔹 Git-Based Deployments – push-to-deploy workflow for websites
+- 🔹 Fail2ban Integration – automatic intrusion prevention
+- 🔹 DNS Zone Management – built-in authoritative DNS
+- 🔹 One-Click App Installers – WordPress and more
+- 🔹 Email Server – mailboxes with webmail
+- 🔹 Teams & Granular Roles – per-resource collaborator access
+- 🔹 Staging Environments – clone, sync, and promote sites
 
 ## Contributing
 Laranode is open-source and welcomes contributions! Feel free to submit issues, feature requests, or pull requests.

app/Actions/Backup/DumpDatabaseAction.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Actions\Backup;
+
+use App\Backup\BackupEngineManager;
+use App\Models\Database;
+
+class DumpDatabaseAction
+{
+    public function __construct(private BackupEngineManager $engineManager) {}
+
+    /**
+     * Write a temp .cnf (mode 0600), call the engine driver, return the dump path.
+     * The .cnf is deleted in finally regardless of success/failure.
+     */
+    public function execute(Database $database, string $tempPath, callable $emit): string
+    {
+        $cnfPath = sys_get_temp_dir().'/laranode-db-'.uniqid().'.cnf';
+
+        // Set umask so the file is created 0600 from the start, eliminating the
+        // TOCTOU window between file_put_contents() and a subsequent chmod().
+        $prevUmask = umask(0177);
+        file_put_contents($cnfPath, "[client]\npassword={$database->db_password}\n");
+        umask($prevUmask);
+
+        try {
+            $driver = $this->engineManager->for($database->engine ?? 'mysql');
+
+            return $driver->dump($database->name, $database->db_user, $cnfPath, $emit);
+        } finally {
+            if (file_exists($cnfPath)) {
+                unlink($cnfPath);
+            }
+        }
+    }
+}

app/Actions/Backup/RetainBackupsAction.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Actions\Backup;
+
+use App\Models\Backup;
+use Illuminate\Contracts\Filesystem\Filesystem;
+
+class RetainBackupsAction
+{
+    /**
+     * Prune backups beyond $retentionCount for the given user/type/target.
+     * Deletes the physical file from $disk then destroys the model row.
+     */
+    public function execute(int $userId, string $type, string $target, int $retentionCount, Filesystem $disk): void
+    {
+        $backups = Backup::where('user_id', $userId)
+            ->where('type', $type)
+            ->where('target', $target)
+            ->where('status', 'completed')
+            ->orderBy('created_at', 'asc')
+            ->get();
+
+        $excess = $backups->slice(0, max(0, $backups->count() - $retentionCount));
+
+        foreach ($excess as $backup) {
+            if ($backup->path) {
+                $disk->delete($backup->path);
+            }
+
+            $backup->delete();
+        }
+    }
+}

app/Actions/Backup/TarFilesAction.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Actions\Backup;
+
+use App\Models\Website;
+use Illuminate\Support\Facades\Process;
+use RuntimeException;
+
+class TarFilesAction
+{
+    /**
+     * Archive the website root via laranode-backup-files.sh, return the archive path.
+     */
+    public function execute(Website $website, string $tempPath, callable $emit): string
+    {
+        $binPath = config('laranode.laranode_bin_path');
+        $sysUser = $website->user->systemUsername ?? ($website->user->username.'_ln');
+
+        $emit("Archiving files for '{$website->url}'...");
+
+        $result = Process::run([
+            'sudo',
+            $binPath.'/laranode-backup-files.sh',
+            $website->websiteRoot,
+            $tempPath,
+            $sysUser,
+        ]);
+
+        if ($result->exitCode() !== 0) {
+            throw new RuntimeException('File archive failed: '.$result->errorOutput());
+        }
+
+        $emit('File archive completed.');
+
+        return $tempPath;
+    }
+}

app/Actions/Backup/UploadToStorageAction.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace App\Actions\Backup;
+
+use Illuminate\Contracts\Filesystem\Filesystem;
+use RuntimeException;
+
+class UploadToStorageAction
+{
+    /**
+     * Stream a local temp file onto the given disk at $remotePath.
+     * Returns $remotePath on success.
+     *
+     * @throws RuntimeException if the file cannot be read or the upload fails.
+     */
+    public function execute(string $localPath, string $remotePath, Filesystem $disk, callable $emit): string
+    {
+        $emit("Uploading backup to storage at '{$remotePath}'...");
+
+        $stream = fopen($localPath, 'rb');
+
+        if ($stream === false) {
+            throw new RuntimeException("Cannot open local file for upload: {$localPath}");
+        }
+
+        try {
+            $disk->writeStream($remotePath, $stream);
+        } finally {
+            if (is_resource($stream)) {
+                fclose($stream);
+            }
+        }
+
+        $emit('Upload completed.');
+
+        return $remotePath;
+    }
+}

app/Actions/Firewall/FirewallLockoutException.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace App\Actions\Firewall;
+
+use RuntimeException;
+
+class FirewallLockoutException extends RuntimeException {}