Squid/ClusterCanvas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Align READMEs with SSH host management and current config layout.

Browse Source
This commit is contained in:
Squid
2026-07-19 22:07:27 +02:00
parent 7631591f30
commit 5307ba1a7b
2 changed files with 73 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+21 -5
View File
@@ -1,6 +1,14 @@
# ClusterCanvas
A web-based dashboard for managing Proxmox VMs, LXC containers, and Docker. After configuration it discovers hosts and shows per‑instance details like hostname, storage and RAM usage, and status. From the same interface you can view logs, run updates, deploy changes, and perform other routine maintenance tasks.
A web UI and Go API for managing remote hosts over SSH. You register hosts manually (grouped as containers, VMs, or Docker for navigation), run shell or script actions on them—including scheduled action groups—and administer users, groups, and sessions with a first-run setup wizard, optional TOTP, and audit logs.
## Features
- **SSH hosts** — Register nodes with generated or imported keys, test connectivity, and organize them under Containers / VMs / Docker categories
- **Action library** — Global shell/script actions (seeded builtins: Uptime, Disk usage, System info) plus custom actions with env vars and optional sudo
- **Action groups** — Per-node ordered items (library refs or local copies), schedules (interval or clock times), `set_variable` / `run_if`, and run logs
- **Auth & access** — Setup wizard, session cookies, group permissions, optional TOTP, and reauth for sensitive operations
- **Activity** — Node and auth audit trails, plus per-node action run history
## Layout
@@ -11,7 +19,7 @@ A web-based dashboard for managing Proxmox VMs, LXC containers, and Docker. Afte
## Prerequisites
- Go 1.22+ (toolchain may download a newer Go as needed)
- Go 1.25+ (toolchain may download a newer Go as needed)
- Node.js 20+ and npm
## Configuration
@@ -20,10 +28,17 @@ Service config lives under **`/etc/ClusterCanvas/`** by default:
| File | Purpose |
|------|---------|
| `settings.json` | Plain base settings (non-secret), including setup/network/security/groups |
| `settings.json` | Setup, network, security, and groups (plain JSON) |
| `passwords.enc` | AES-GCM encrypted user credentials (argon2id hashes, TOTP secrets) |
| `sessions.enc` | AES-GCM encrypted session store |
| `secrets.enc` | AES-GCM encrypted JSON secrets (integrations, etc.) |
| `secrets.enc` | AES-GCM encrypted secrets placeholder (integrations not wired yet) |
| `nodes.json` | Registered SSH hosts |
| `node-keys.enc` | AES-GCM encrypted SSH private keys |
| `actions.json` | Global action library |
| `node-action-groups.json` | Per-node action groups and schedules |
| `node-audit.json` | Node mutation / SSH-test audit trail |
| `auth-audit.json` | Auth / user / group audit trail |
| `action-logs/` | Per-node action run history |
**Config directory precedence** (highest first):
@@ -49,7 +64,7 @@ export CLUSTERCANVAS_CONFIG_KEY="$(openssl rand -base64 32)"
make dev
```
Keep the same key across restarts if you already ran setup — changing it makes existing `passwords.enc` / `sessions.enc` unreadable.
Keep the same key across restarts if you already ran setup — changing it makes existing `passwords.enc` / `sessions.enc` / `node-keys.enc` unreadable.
### First-run setup
@@ -111,6 +126,7 @@ REMOTEDEV_USER=youruser REMOTEDEV_HOST=192.168.1.50 make remotedev
What lands on the VM: `clustercanvas-server`, `clustercanvas-webui`, and `web/` (built SPA). Config is stored under `$(REMOTEDEV_DIR)/config` with the remotedev encryption key so the setup wizard works without extra env setup. Transfer uses `scp` (OpenSSH only on the remote—no `rsync` required). Re-running `make remotedev` stops any previous instance on the VM before uploading so binaries are not busy. The webui binary serves the SPA and proxies `/api` and `/health` to the API. Open `http://<vm-ip>:5173`. Ctrl+C stops both remote processes. A reverse proxy in front of these ports is optional and separate.
**Do not use `REMOTEDEV_CONFIG_KEY` (or its default) in production** — generate a unique key with `openssl rand -base64 32` instead.
## Test
```bash
webui/README.md
+52 -25
View File
@@ -1,32 +1,59 @@
# React + TypeScript + Vite
# ClusterCanvas web UI
This template provides a minimal setup to get React working in Vite with HMR and some Oxlint rules.
React 19 + TypeScript + Vite SPA for ClusterCanvas. It talks to the Go API over `/api` and `/health`.
Currently, two official plugins are available:
For service config, remotedev, and repo-wide build/test targets, see the [root README](../README.md).
- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
## Develop
## React Compiler
From this directory:
The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
## Expanding the Oxlint configuration
If you are developing a production application, we recommend enabling type-aware lint rules by installing `oxlint-tsgolint` and editing `.oxlintrc.json`:
```json
{
"$schema": "./node_modules/oxlint/configuration_schema.json",
"plugins": ["react", "typescript", "oxc"],
"options": {
"typeAware": true
},
"rules": {
"react/rules-of-hooks": "error",
"react/only-export-components": ["warn", { "allowConstantExport": true }]
}
}
```bash
npm install
npm run dev
```
See the [Oxlint rules documentation](https://oxc.rs/docs/guide/usage/linter/rules) for the full list of rules and categories.
Or from the repo root: `make webui` (UI only) or `make dev` (API + UI).
The Vite dev server listens on `:5173` and proxies `/api` and `/health` to `http://localhost:8080` (see `vite.config.ts`).
Optional: set `VITE_API_BASE_URL` if you call the API without the Vite proxy (defaults to `http://localhost:8080`). An empty value means same-origin requests (used by `make remotedev` builds).
## Scripts
| Script | Purpose |
|--------|---------|
| `npm run dev` | Vite dev server with HMR |
| `npm run build` | Typecheck + production build to `dist/` |
| `npm run preview` | Serve the production build locally |
| `npm test` | Vitest (jsdom) once |
| `npm run test:watch` | Vitest in watch mode |
| `npm run lint` | Oxlint (see `.oxlintrc.json`) |
## App map
Flow: **setup wizard** → **login** → main shell.
| Area | Notes |
|------|-------|
| Overview | Placeholder for a future dashboard |
| Containers / Docker / VMs | UI categories for manually registered SSH hosts |
| Activity | Node and auth audit logs (when permitted) |
| Profile | Password change and TOTP enroll/disable |
| Configuration | Users, groups, roles catalog, actions, security, network; Integrations / Advanced are placeholders |
Node detail tabs: **Overview** (metadata), **Actions** (groups, schedules, run), **Logs** (action run history).
### Key source files
| Path | Role |
|------|------|
| `src/App.tsx` | Shell, routing state, main screens |
| `src/api/client.ts` | HTTP client and API types |
| `src/navigation.ts` | Section / tab / URL helpers |
| `src/NodeDetailPanel.tsx` | Per-node overview, actions, logs |
| `src/SetupWizard.tsx` | First-run setup |
## Stack
React 19, Vite 8, Vitest + Testing Library, Oxlint. React Compiler is not enabled.