added install script for agent
changed backend to agent
This commit is contained in:
Philipp
+23
-23
@@ -2,11 +2,11 @@
|
||||
|
||||
## Overview
|
||||
|
||||
Build a dark-mode backup operations dashboard (React frontend + Node.js backend) to manage incremental ZFS block-level backups of Incus VMs via Restic to S3 storage.
|
||||
Build a dark-mode backup operations dashboard (React frontend + Node.js agent) to manage incremental ZFS block-level backups of Incus VMs via Restic to S3 storage.
|
||||
|
||||
The UI should be visually inspired by [Zerobyte](https://zerobyte.app/): calm dark operator interface, compact status panels, clear backup lifecycle visibility, and strong restore safeguards. This is an application dashboard, not a marketing landing page.
|
||||
|
||||
The backend is a **safe CLI orchestration layer** that executes native host commands (`incus`, `zfs`, `restic`, `udevadm`, `dd`) and exposes structured REST APIs to the frontend.
|
||||
The agent is a **safe CLI orchestration layer** that executes native host commands (`incus`, `zfs`, `restic`, `udevadm`, `dd`) and exposes structured REST APIs to the frontend.
|
||||
|
||||
Core product goals:
|
||||
|
||||
@@ -23,10 +23,10 @@ Core product goals:
|
||||
| Layer | Technology |
|
||||
|---|---|
|
||||
| Frontend | React (Vite), Tailwind CSS, Lucide Icons, Axios |
|
||||
| Backend | Node.js, Express |
|
||||
| Agent | Node.js, Express |
|
||||
| Communication | REST API |
|
||||
| Execution model | Background jobs with per-VM locks |
|
||||
| Host requirement | Backend must run as root/sudo on the Incus host (needs `/dev/zvol/` and Incus Unix socket access) |
|
||||
| Host requirement | Agent must run as root/sudo on the Incus host (needs `/dev/zvol/` and Incus Unix socket access) |
|
||||
|
||||
---
|
||||
|
||||
@@ -34,7 +34,7 @@ Core product goals:
|
||||
|
||||
```
|
||||
/
|
||||
├── backend/
|
||||
├── agent/
|
||||
│ ├── .env
|
||||
│ ├── package.json
|
||||
│ └── src/
|
||||
@@ -68,7 +68,7 @@ Core product goals:
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables (`backend/.env`)
|
||||
## Environment Variables (`agent/.env`)
|
||||
|
||||
```env
|
||||
# Restic & S3 Config
|
||||
@@ -89,7 +89,7 @@ API_TOKEN="change-me"
|
||||
|
||||
---
|
||||
|
||||
## Backend Implementation Principles
|
||||
## Agent Implementation Principles
|
||||
|
||||
### Safe Command Execution
|
||||
|
||||
@@ -115,7 +115,7 @@ API_TOKEN="change-me"
|
||||
}
|
||||
```
|
||||
|
||||
The backend must reject restore requests where `confirmVmName !== vmName`.
|
||||
The agent must reject restore requests where `confirmVmName !== vmName`.
|
||||
|
||||
### Job Model
|
||||
|
||||
@@ -151,7 +151,7 @@ Rules:
|
||||
|
||||
#### `GET /api/health`
|
||||
|
||||
**Purpose:** Show backend and host command readiness.
|
||||
**Purpose:** Show agent and host command readiness.
|
||||
|
||||
**Checks:**
|
||||
- Required environment variables are present.
|
||||
@@ -294,7 +294,7 @@ restic forget --tag "<vmName>" --keep-daily 7 --prune
|
||||
```
|
||||
|
||||
**Error Handling / Cleanup:**
|
||||
If any step (1–4) fails, the backend **must** still execute the following cleanup commands before marking the job as failed:
|
||||
If any step (1–4) fails, the agent **must** still execute the following cleanup commands before marking the job as failed:
|
||||
- `zfs set snapdev=hidden <ZFS_POOL_NAME>/virtual-machines/<vmName>.block`
|
||||
- `incus snapshot delete <vmName> s3-backup-<timestamp>` (ignore errors if snapshot doesn't exist)
|
||||
|
||||
@@ -362,7 +362,7 @@ incus start <vmName>
|
||||
|
||||
- Tailwind dark theme base: `bg-zinc-950`, `text-zinc-100`.
|
||||
- Create an Axios instance pointing to `http://localhost:3000/api`.
|
||||
- Display backend errors as both toast notifications and persistent job errors where relevant.
|
||||
- Display agent errors as both toast notifications and persistent job errors where relevant.
|
||||
- Use Lucide icons for actions and status indicators.
|
||||
|
||||
### Visual Direction
|
||||
@@ -458,13 +458,13 @@ The interface should follow the Zerobyte-inspired operator dashboard direction:
|
||||
|
||||
| Layer | Requirement |
|
||||
|---|---|
|
||||
| Backend command execution | Use `spawn` with argument arrays; no shell interpolation for user input |
|
||||
| Backend validation | Validate VM names against Incus and snapshot IDs against Restic |
|
||||
| Backend jobs | Backup/restore run as jobs with status, logs, timestamps, and errors |
|
||||
| Backend locking | Only one active backup/restore job per VM |
|
||||
| Backend backup cleanup | On failure in backup steps 1–4, always hide snapdev and delete the temp snapshot |
|
||||
| Backend restore cleanup | If restore fails after `volmode=dev`, attempt to restore `volmode=none` |
|
||||
| Backend errors | Return structured `{ "error": "..." }`; job failures must also be visible via `/api/jobs/:jobId` |
|
||||
| Agent command execution | Use `spawn` with argument arrays; no shell interpolation for user input |
|
||||
| Agent validation | Validate VM names against Incus and snapshot IDs against Restic |
|
||||
| Agent jobs | Backup/restore run as jobs with status, logs, timestamps, and errors |
|
||||
| Agent locking | Only one active backup/restore job per VM |
|
||||
| Agent backup cleanup | On failure in backup steps 1–4, always hide snapdev and delete the temp snapshot |
|
||||
| Agent restore cleanup | If restore fails after `volmode=dev`, attempt to restore `volmode=none` |
|
||||
| Agent errors | Return structured `{ "error": "..." }`; job failures must also be visible via `/api/jobs/:jobId` |
|
||||
| Frontend errors | Show immediate toast plus persistent job error/details |
|
||||
| Frontend restore action | Always show destructive confirmation modal and require VM-name confirmation |
|
||||
|
||||
@@ -472,8 +472,8 @@ The interface should follow the Zerobyte-inspired operator dashboard direction:
|
||||
|
||||
## MVP Implementation Order
|
||||
|
||||
1. Scaffold backend and frontend folders.
|
||||
2. Implement backend config validation and safe command executor.
|
||||
1. Scaffold agent and frontend folders.
|
||||
2. Implement agent config validation and safe command executor.
|
||||
3. Implement `GET /api/health`.
|
||||
4. Implement `GET /api/vms`.
|
||||
5. Implement `GET /api/snapshots/:vmName`.
|
||||
@@ -483,16 +483,16 @@ The interface should follow the Zerobyte-inspired operator dashboard direction:
|
||||
9. Build VM detail UI with snapshot table and job status panel.
|
||||
10. Implement restore job flow with defensive validation and cleanup.
|
||||
11. Wire restore modal with explicit destructive confirmation.
|
||||
12. Add deployment notes for running backend as root/sudo on the Incus host.
|
||||
12. Add deployment notes for running agent as root/sudo on the Incus host.
|
||||
|
||||
---
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
### Backend
|
||||
### Agent
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
cd agent
|
||||
npm init -y
|
||||
npm install express cors dotenv
|
||||
# Copy .env and fill in values
|
||||
|
||||
Reference in New Issue
Block a user