79 lines
1.8 KiB
Markdown
79 lines
1.8 KiB
Markdown
# ClusterCanvas
|
||
|
||
A web-based dashboard for managing Proxmox VMs and LXC containers. 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.
|
||
|
||
## Layout
|
||
|
||
| Path | Role |
|
||
|------|------|
|
||
| `service/` | Go HTTP API |
|
||
| `webui/` | Vite + React + TypeScript SPA |
|
||
|
||
## Prerequisites
|
||
|
||
- Go 1.22+
|
||
- Node.js 20+ and npm
|
||
|
||
## Configuration
|
||
|
||
Service config lives under **`/etc/ClusterCanvas/`** by default:
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `settings.json` | Plain base settings (non-secret) |
|
||
| `secrets.enc` | AES-256-GCM encrypted JSON secrets |
|
||
|
||
**Config directory precedence** (highest first):
|
||
|
||
1. `-configdir` flag — e.g. `./bin/clustercanvas-server -configdir="~/.myconfigs"`
|
||
2. `CLUSTERCANVAS_CONFIG_DIR` environment variable
|
||
3. `/etc/ClusterCanvas`
|
||
|
||
A leading `~/` in the path is expanded to the user home directory.
|
||
|
||
**Secrets encryption key:** set `CLUSTERCANVAS_CONFIG_KEY` to a base64-encoded 32-byte key:
|
||
|
||
```bash
|
||
openssl rand -base64 32
|
||
export CLUSTERCANVAS_CONFIG_KEY='…paste output…'
|
||
```
|
||
|
||
## Run
|
||
|
||
Start API and web UI together (API `:8080`, UI `:5173`; Ctrl+C stops both):
|
||
|
||
```bash
|
||
make dev
|
||
```
|
||
|
||
Or start them separately:
|
||
|
||
```bash
|
||
make service # API on :8080 (override with PORT)
|
||
make webui # UI on :5173 (proxies /health and /api)
|
||
```
|
||
|
||
Custom config directory for the API:
|
||
|
||
```bash
|
||
cd service && go run ./cmd/server -configdir="$HOME/.myconfigs"
|
||
```
|
||
|
||
Optional: set `VITE_API_BASE_URL` (defaults to `http://localhost:8080`) if you call the API without the Vite proxy.
|
||
|
||
## Test
|
||
|
||
```bash
|
||
make test
|
||
```
|
||
|
||
This runs `go test ./...` in `service/` and Vitest in `webui/`.
|
||
|
||
## Build
|
||
|
||
```bash
|
||
make build
|
||
```
|
||
|
||
Produces `bin/clustercanvas-server` and `webui/dist/`.
|