From 8697c9f40531e67d668d7681c6a946a55d31344d Mon Sep 17 00:00:00 2001
From: Philipp <schlottmann@digital-droplets.de>
Date: Thu, 21 May 2026 08:18:09 +0200
Subject: [PATCH] first commit

---
 README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..12e6d77
--- /dev/null
+++ b/README.md
@@ -0,0 +1,52 @@
+# Incus Backup UI
+
+Dark-mode control plane for Incus VM backups using ZFS block devices, Restic, and S3-compatible storage.
+
+## Layout
+
+- `backend/`: Express API that 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 health, VM status, snapshots, backup jobs, and explicit destructive restore confirmation.
+- `incus-backup-ui-plan.md`: Product and implementation plan.
+
+## Backend
+
+```bash
+cd backend
+cp .env.example .env
+npm install
+npm run dev
+```
+
+The backend must run on the 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.
+
+Required commands:
+
+- `incus`
+- `zfs`
+- `restic`
+- `udevadm`
+- `dd`
+
+## Frontend
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Set `VITE_API_URL` if the API is not available at `http://localhost:3000/api`.
+
+If `API_TOKEN` is set in the backend, set matching `VITE_API_TOKEN` for the frontend.
+
+## Settings Page
+
+The UI includes a Settings page for editing the backend environment values directly. It writes to `backend/.env` through `GET /api/settings` and `PUT /api/settings`.
+
+If `API_TOKEN` is set from the Settings page, the browser stores that token locally and immediately uses it for subsequent API requests. If a token is already configured on the backend and the browser does not know it yet, start the frontend with `VITE_API_TOKEN` or clear/update the token manually in browser storage.
+
+Changing most values applies to new API calls and jobs immediately. Changing `PORT` requires restarting the backend 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. Restore jobs are never retried automatically.