ClusterCanvas/README.md

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.

Layout

Path	Role
service/	Go HTTP API
webui/	Vite + React + TypeScript SPA

Prerequisites

• Go 1.22+ (toolchain may download a newer Go as needed)
• Node.js 20+ and npm

Configuration

Service config lives under /etc/ClusterCanvas/ by default:

File	Purpose
settings.json	Plain base settings (non-secret), including setup/network/security/groups
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.)

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 16-, 24-, or 32-byte key (required for first-run setup and login):

openssl rand -base64 32
export CLUSTERCANVAS_CONFIG_KEY='…paste output…'

For a one-off shell session you can also prefix the command:

CLUSTERCANVAS_CONFIG_KEY="$(openssl rand -base64 32)" make service
# or with make dev:
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.

First-run setup

On a clean install (setup_completed is false / missing), the web UI opens a setup wizard instead of the dashboard. It creates the admin user, Administrators group, network settings (listen address, optional public hostname, IP allow/deny lists), and security policy, then requires sign-in.

Session cookies use the __Host-ClusterCanvas-Session name with Secure, HttpOnly, SameSite=Strict, and Path=/ (no Domain). Production should set a public hostname and terminate TLS at a reverse proxy so browsers reach the UI over HTTPS. Listen address changes apply on the next process restart.

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. An empty value means same-origin requests (used by make remotedev).

Remote dev (VM without SDKs)

Build on your machine, copy runnables over SSH, and run both processes on a remote host (no Go/Node required there—only OpenSSH).

Prepare host/user once (recommended):

cp remotedev.mk.example remotedev.mk
# edit REMOTEDEV_USER and REMOTEDEV_HOST in remotedev.mk
make remotedev

Or pass them on the CLI:

REMOTEDEV_USER=youruser REMOTEDEV_HOST=192.168.1.50 make remotedev
# or combined: REMOTEDEV_HOST=youruser@192.168.1.50 make remotedev

Env	Default	Meaning
REMOTEDEV_HOST	(required)	Host/IP, user@host, or an SSH config Host alias
REMOTEDEV_USER	(optional)	Username; combined as user@host when set
REMOTEDEV_DIR	clustercanvas-remotedev	Remote directory (~/… is fine; relative paths are under the remote home)
REMOTEDEV_CONFIG_KEY	(baked-in remotedev key)	Dev-only CLUSTERCANVAS_CONFIG_KEY exported on the VM (override in remotedev.mk)
PORT	8080	API listen port on the VM (all interfaces)
WEBUI_PORT	5173	Web UI listen port on the VM (all interfaces)

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

make test

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

Build

make build

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