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:

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):

make dev

Or start them separately:

make service   # API on :8080 (override with PORT)
make webui     # UI on :5173 (proxies /health and /api)

Custom config directory for the API:

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

make test

This runs go test ./... in service/ and Vitest in webui/.

Build

make build

Produces bin/clustercanvas-server and webui/dist/.