# Incus Backup UI

Dark-mode control plane for Incus VM backups using ZFS block devices, Restic, and S3-compatible storage.

Backups include the instance disk or dataset plus Incus metadata captured with `incus config show`, `incus config show --expanded`, `incus info`, and snapshot listing. VM disks are stored as `.raw`; containers are stored as ZFS send streams (`.zfs`).

## Layout

- `management/`: Central Express API with cookie login, SQLite storage, node registry, central schedules, and proxy calls to node agents.
- `backend/`: Node agent API that runs on each Incus host, validates Incus VMs, runs host commands with `spawn`, manages in-memory jobs, and enforces one active backup/restore per VM.
- `frontend/`: React/Vite dashboard for management login, node management, health, VM status, snapshots, backup jobs, and explicit destructive restore confirmation.
- `incus-backup-ui-plan.md`: Product and implementation plan.

## Node Agent

```bash
cd backend
cp .env.example .env
npm install
npm run dev
```

The node agent must run on every Incus host with permission to access Incus, ZFS, `/dev/zvol`, Restic, and S3 credentials. In production this usually means running it as root or through a tightly scoped service account with the needed privileges.

Set `API_TOKEN` in `backend/.env`; the management server uses that token when calling the agent. The token is required and must be at least 32 characters long.

The agent can serve HTTPS directly for private networks:

```env
HTTPS_ENABLED=true
TLS_CERT_FILE="/etc/incus-backup-agent/tls.crt"
TLS_KEY_FILE="/etc/incus-backup-agent/tls.key"
```

Required commands:

- `incus`
- `zfs`
- `zpool`
- `restic`
- `udevadm`
- `dd`

## Management API

```bash
cd management
cp .env.example .env
npm install
npm run dev
```

The management API stores nodes, users, sessions, and central schedules in SQLite. Configure the first admin user through `AUTH_USERNAME` and `AUTH_PASSWORD` before the first start. Startup fails if the initial password is missing.

Agent URLs must use `https://` by default. For local development only, set `ALLOW_INSECURE_AGENT_HTTP=true` in `management/.env` to permit `http://` node URLs.

For internal/self-signed agent certificates, set `AGENT_CA_FILE` in `management/.env` to the CA certificate that signed the agent certificates.

The management API uses Node's built-in SQLite module and requires Node.js 22.5 or newer.

Reset an existing admin password without deleting the database:

```bash
cd management
npm run reset-password -- admin "new-password"
```

## Frontend

```bash
cd frontend
npm install
npm run dev
```

Set `VITE_API_URL` if the management API is not available at `http://localhost:3100/api`.

## Settings Page

The UI includes a Settings page for editing selected node-agent environment values through the management API. The management server forwards those requests to the selected node agent.

Changing most node-agent values applies to new API calls and jobs immediately. Changing a node-agent `PORT` requires restarting that agent process.

## Safety Notes

Restore is intentionally guarded twice: the backend validates the snapshot against the VM, and the UI requires typing the VM name before sending the restore request. VM restores create a pre-restore ZFS snapshot and roll back to it if writing the disk fails. Restore jobs are never retried automatically.

## Deployment

See `docs/deployment.md` for systemd units, management/agent split, and production setup notes.