From 20aec565ed45dd933ace4be07d9604ce9c1ca932 Mon Sep 17 00:00:00 2001 From: boban Date: Sun, 21 Jun 2026 16:52:00 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20enterprise=20README=20for=20Gitea=20?= =?UTF-8?q?=E2=80=94=20branded=20hero=20+=20architecture=20diagram?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rebuild the README around the product's "Tactical Terminal" design system (dark graphite, signal-orange, cyan, mono type) so it reads as a professional, self-hosted enterprise product instead of a plain text file: - docs/assets/clusev-banner.svg — hero banner with the Clusev wordmark, tagline, brand chips, and a live "fleet" node-graph (control-plane hub → server cards with the online/warning/offline status triad + CPU bars and animated data pulses). Self-contained: the real product fonts (Chakra Petch + JetBrains Mono) are embedded base64 so Gitea's -rendered SVG shows pixel-correct type. - docs/assets/clusev-architecture.svg — Operator → Control plane → Fleet diagram (HTTPS/WS · Reverb in, SSH+SFTP · phpseclib out), same brand language. - README.md — centered hero, brand-matched shields badges, anchor nav, a "why" three-up, a Features table, the architecture diagram + a tech-stack table, and the existing install / domain-TLS / updating / security-recovery content kept verbatim (now with a WireGuard feature row). All graphics are external SVG files (Gitea strips inline ); relative paths resolve on the default branch. Co-Authored-By: Claude Opus 4.8 --- README.md | 178 ++++++++++++++++++++-------- docs/assets/clusev-architecture.svg | 21 ++++ docs/assets/clusev-banner.svg | 70 +++++++++++ 3 files changed, 218 insertions(+), 51 deletions(-) create mode 100644 docs/assets/clusev-architecture.svg create mode 100644 docs/assets/clusev-banner.svg diff --git a/README.md b/README.md index 6b2dde6..0777738 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,90 @@ -# Clusev +
-**Self-hosted control panel for a fleet of Linux servers — one dashboard, agentless over SSH.** +Clusev — self-hosted control plane for a fleet of Linux servers -Clusev is the control plane: a modern, security-first web UI that administers your servers by talking -to them directly over SSH (exec + SFTP via phpseclib). It installs nothing on the target machines and -never reimplements their daemons. Multi-server management is free and never paywalled. +
+ +**One dashboard for your whole fleet. Agentless over SSH. Self-hosted, security-first, open core.** + +[![License](https://img.shields.io/badge/license-AGPL--3.0-FF6B2C?style=flat-square&labelColor=0F1318)](#license) +[![Version](https://img.shields.io/badge/release-v0.9.40-FF6B2C?style=flat-square&labelColor=0F1318)](https://git.bave.dev/boban/clusev) +[![Laravel](https://img.shields.io/badge/Laravel-13-9DAAB6?style=flat-square&labelColor=0F1318)](https://laravel.com) +[![Livewire](https://img.shields.io/badge/Livewire-3-9DAAB6?style=flat-square&labelColor=0F1318)](https://livewire.laravel.com) +[![Docker](https://img.shields.io/badge/Docker-ready-43C1D8?style=flat-square&labelColor=0F1318)](#quick-start) +[![Self-hosted](https://img.shields.io/badge/self--hosted-Debian%20%2F%20Ubuntu-35D07F?style=flat-square&labelColor=0F1318)](#requirements) + +[**Features**](#features) · [**Architecture**](#architecture) · [**Quick start**](#quick-start) · [**Domain & TLS**](#access-domain--tls) · [**Security**](#security--recovery) · [**License**](#license) + +
+ +--- + +## What is Clusev + +**Clusev** is the control plane for a fleet of Linux servers — a modern, security-first web UI that +administers your machines by talking to them **directly over SSH** (exec + SFTP via +[phpseclib](https://phpseclib.com)). It installs **nothing** on the target servers and never +reimplements their daemons; it orchestrates the real ones. + +> **Multi-server management is free and never paywalled.** Optional Pro modules (SSO/LDAP, RBAC, +> audit export, alerting) are separate — the core stays open. + +
+ +| | | | +|:--|:--|:--| +| **Agentless** | **Security-first** | **Self-hosted** | +| Pure SSH + SFTP. No daemon, no package, no push-agent on your servers. | 2FA, encrypted credential vault, tamper-evident audit log, per-device sessions. | One Docker stack on one VM. Your servers, your data, your keys. | + +
+ +--- ## Features -- **Dashboard & live metrics** — CPU, memory, load and disk per server, streamed in real time. -- **systemd services** — list, start/stop/restart, live journal tail. -- **SFTP file manager** — browse, edit text files, preview images. -- **Server details & hardening** — resource gauges, volumes, interfaces, SSH keys; UFW/firewalld - rules and fail2ban status with one-click controls; and a one-click "generate an SSH key and disable - password login, safely" flow. -- **Security** — optional, pluggable 2FA (TOTP and/or hardware security keys, or off), one-time - backup codes, an encrypted SSH-credential vault, and a complete, tamper-evident audit log. -- **Multiple administrators** — add further admin accounts; every action is attributed in the audit - log; view and revoke active sessions (per device, per user, or globally). -- **Domain, TLS & e-mail** — run on a bare IP over HTTP, set a domain for automatic HTTPS, or put your - own reverse proxy in front. Configure SMTP in-panel for password-reset e-mails. +| Capability | What you get | +|:--|:--| +| **Dashboard & live metrics** | CPU, memory, load and disk per server, streamed in real time over WebSockets. | +| **systemd services** | List, start / stop / restart, and tail the live journal — per service, per server. | +| **SFTP file manager** | Browse the remote filesystem, edit text files in place, preview images. | +| **Server details & hardening** | Resource gauges, volumes, interfaces and SSH keys; UFW / firewalld rules and fail2ban status with one-click controls; a guided _"generate an SSH key and disable password login, safely"_ flow. | +| **Security** | Pluggable 2FA (TOTP and/or hardware keys, or off), one-time backup codes, an encrypted SSH-credential vault, and a complete tamper-evident audit log. | +| **Multiple administrators** | Add further admin accounts — every action is attributed in the audit log; view and revoke active sessions per device, per user, or globally. | +| **Domain, TLS & e-mail** | Run on a bare IP over HTTP, set a domain for automatic Let's Encrypt HTTPS, or sit behind your own reverse proxy. In-panel SMTP for password-reset mail. | +| **WireGuard (built-in)** | Stand up a WireGuard tunnel from the dashboard, manage peers and live status, and optionally gate the panel — and even SSH — to the tunnel only. | -The panel is built on Laravel 13, Livewire 3, Tailwind v4, Laravel Reverb (realtime), Redis, MariaDB -and phpseclib — all running in Docker. The interface is in German (English available). +The interface is **German by default** (English available). Status is shown the operational way — +colour, dots and pills — never emoji. -## Requirements +--- -- A **Debian or Ubuntu** server (a small VM is enough) with **root** access. -- A public IP. Optionally a domain whose DNS points at the server (for automatic HTTPS). -- Only **git** to fetch the repo (one line below) — the installer sets up Docker and everything else. +## Architecture -## Install +
+Operator → Clusev control plane → your fleet +
+ +Laravel is the **control plane**, not a re-implementation of your servers. The browser talks to it +over HTTPS and a Reverb WebSocket for live telemetry; it reaches each server over **SSH exec + SFTP** +using credentials sealed in an encrypted vault that never leaves the control plane. Everything runs as +one Docker stack — `app` (php-fpm + nginx + Vite), `reverb`, `queue`, `scheduler`, `mariadb`, +`redis` — on a single VM. + +| Layer | Technology | +|:--|:--| +| Framework | **Laravel 13** | +| UI / interactivity | **Livewire 3** (class-based) | +| Styling | **Tailwind v4** (CSS-first, `@theme`) | +| Realtime | **Laravel Reverb** + Echo | +| Queue / cache | **Redis** | +| Database | **MariaDB** | +| SSH transport | **phpseclib** (exec + SFTP) | +| Reverse proxy / TLS | **Caddy** (automatic Let's Encrypt) | +| Packaging | **Docker** + Docker Compose | + +--- + +## Quick start ```bash sudo apt-get update && sudo apt-get install -y git # minimal images often lack git @@ -39,16 +93,16 @@ cd clusev sudo ./install.sh ``` -The installer is idempotent (safe to re-run) and, in one pass: +The installer is **idempotent** (safe to re-run) and, in one pass: 1. Installs **Docker** (Debian/Ubuntu, from Docker's official repository) if it isn't already present. -2. Creates a dedicated **`clusev`** system user — in the `docker` group, owning and running the stack — - with a random password. -3. Asks for a **domain** (leave empty for IP access) and an **admin e-mail** (leave empty for the - default **`admin@clusev.local`**), or reads `CLUSEV_DOMAIN` / `CLUSEV_ADMIN_EMAIL` from the - environment for an unattended install. If you give a domain it - checks whether DNS already points here: if so a certificate is obtained automatically; if not, it - warns you and lets you take the domain anyway (HTTP until DNS is correct) or continue on the IP. +2. Creates a dedicated **`clusev`** system user — in the `docker` group, owning and running the stack + — with a random password. +3. Asks for a **domain** (leave empty for IP access) and an **admin e-mail** (default + **`admin@clusev.local`**), or reads `CLUSEV_DOMAIN` / `CLUSEV_ADMIN_EMAIL` from the environment for + an unattended install. With a domain it checks whether DNS already points here: if so a certificate + is obtained automatically; if not, it warns you and lets you take the domain anyway (HTTP until DNS + is correct) or continue on the IP. 4. Generates all secrets (once — never regenerated on re-run), builds the image, starts the stack, runs the migrations, and creates the first administrator with the **default password `clusev`** (you are forced to change it on first login). @@ -58,27 +112,40 @@ When it finishes, the terminal prints a single summary: the **dashboard URL**, t (your e-mail — `admin@clusev.local` if you left it empty — plus the default password **`clusev`**), and the **`clusev` host user** + its random password (shown **only once** — note it down). -Log in with your admin e-mail (default **`admin@clusev.local`**) and the password **`clusev`** — the -panel then **forces you to set a new password immediately**. Do this right away: `clusev` is a known -default, so the account is only safe once you've changed it. You can change the login e-mail later -under **Settings → Profile**. 2FA is **optional but recommended** — enable TOTP and/or a security key -from **Settings → Security** whenever you like. +### First login -## Access, domain & TLS +Log in with your admin e-mail and the password **`clusev`** — the panel then **forces you to set a new +password immediately**. Do this right away: `clusev` is a known default, so the account is only safe +once changed. You can change the login e-mail later under **Settings → Profile**. 2FA is **optional but +recommended** — enable TOTP and/or a security key from **Settings → Security** whenever you like. + +--- + +## Requirements + +- A **Debian or Ubuntu** server (a small VM is enough) with **root** access. +- A **public IP**. Optionally a domain whose DNS points at the server (for automatic HTTPS). +- Only **git** to fetch the repo — the installer sets up Docker and everything else. + +--- + +## Access, domain & TLS - **Bare IP (no domain):** served over plain HTTP at `http://`. This address always stays reachable as a recovery path, even after a domain is configured. -- **With a domain:** set it during install or later under **System → Domain & TLS**. The panel obtains - and renews a Let's Encrypt certificate automatically and serves HTTPS — just point DNS at the server. - (Let's Encrypt needs publicly reachable ports 80/443.) -- **Behind your own reverse proxy** (one that already terminates TLS): switch *TLS-Terminierung* to - **Externer Reverse-Proxy** in System → Domain & TLS. The panel then serves HTTP only and trusts the - proxy's forwarded scheme — set `TRUSTED_PROXY_CIDR` to the proxy's address and firewall the HTTP +- **With a domain:** set it during install or later under **System → Domain & TLS**. The panel + obtains and renews a Let's Encrypt certificate automatically and serves HTTPS — just point DNS at the + server. (Let's Encrypt needs publicly reachable ports 80/443.) +- **Behind your own reverse proxy** (one that already terminates TLS): switch _TLS-Terminierung_ to + **Externer Reverse-Proxy** in System → Domain & TLS. The panel then serves HTTP only and trusts + the proxy's forwarded scheme — set `TRUSTED_PROXY_CIDR` to the proxy's address and firewall the HTTP port so only the proxy can reach it. Domain/TLS changes apply on a stack restart — use the **"Jetzt neu starten"** button in System (no terminal needed; a small, scoped host service performs the restart). +--- + ## Updating ```bash @@ -86,11 +153,13 @@ cd clusev sudo ./update.sh # pulls the latest code, then rebuilds, restarts and migrates ``` -`update.sh` fast-forwards the repo (it never discards local changes), re-runs the idempotent -installer non-interactively, and updates itself if the script changed. Secrets and the configured -domain / e-mail are preserved. (The older two-step `git pull && sudo ./install.sh` still works.) +`update.sh` fast-forwards the repo (it never discards local changes), re-runs the idempotent installer +non-interactively, and updates itself if the script changed. Secrets and the configured domain / +e-mail are preserved. (The older two-step `git pull && sudo ./install.sh` still works.) -## Account recovery +--- + +## Security & recovery The **forgot-password** screen offers self-service recovery: an **e-mail reset link** (valid 15 minutes) when SMTP is configured, or an inline **2FA-proof reset** (e-mail + TOTP or a backup code + @@ -108,8 +177,15 @@ This clears the second factor so you can set a new password on the next login. T is documented in-panel under Settings → Security and is deliberately not shown on the public forgot-password screen.) +--- + ## License -Open core, **AGPL-3.0** — multi-server fleet management is always free; optional Pro modules -(SSO/LDAP, RBAC, audit export, alerting) are separate. Project home: -. +Open core, **AGPL-3.0** — multi-server fleet management is always free; optional Pro modules (SSO/LDAP, +RBAC, audit export, alerting) are separate. + +
+ +**Project home — [git.bave.dev/boban/clusev](https://git.bave.dev/boban/clusev)** + +
diff --git a/docs/assets/clusev-architecture.svg b/docs/assets/clusev-architecture.svg new file mode 100644 index 0000000..a6c34c5 --- /dev/null +++ b/docs/assets/clusev-architecture.svg @@ -0,0 +1,21 @@ + + + + + + + + + + +ARCHITECTURE +CONTROL PLANE · AGENTLESS · SSH +OPERATORWeb UI2FA · audit log +HTTPS / WSReverbSSH + SFTPphpseclib +▢ DOCKERone VM · Debian/UbuntuCONTROL PLANELaravel 13Livewire 3ReverbRedisMariaDBCaddy · TLSEncrypted SSH-credential vaultkeys never leave the control planeorchestrates — never reimplements daemons +YOUR FLEETweb-01nginx · phpONLINEno agentdb-primarymariadbONLINEno agentcache-02redisWARNno agentedge-eucaddyONLINEno agentnothing installed · agentless · over SSH + \ No newline at end of file diff --git a/docs/assets/clusev-banner.svg b/docs/assets/clusev-banner.svg new file mode 100644 index 0000000..c8d80e7 --- /dev/null +++ b/docs/assets/clusev-banner.svg @@ -0,0 +1,70 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +AGENTLESS · SSH · FLEET CONTROL +CLUSEV + +One dashboard for a fleet of Linux servers. +Self-hosted control plane · metrics · services · SFTP · hardening · audit. +AGPL-3.0Laravel 13Livewire 3Dockerv0.9.40 + + +FLEET · LIVE STATUS + +CONTROLPLANE +web-01db-primarycache-02edge-eubackup-03 + + + + + + + \ No newline at end of file