Add README with setup instructions and current build status

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-09-14 21:57:38 +02:00
parent 6bd2ed52c1
commit 89919fdbff
1 changed files with 71 additions and 0 deletions
@@ -0,0 +1,71 @@
+# Homelab Manager
+
+A single dashboard for a homelab: Proxmox, Synology DSM, Semaphore, Tailscale,
+Gitea, and Dockhand/Docker status and basic actions, plus DNS record
+management, an IP address inventory (IPAM), and a secret-expiry tracker
+(ported from [Sloth Manager](../Sloth%20manager)) and scheduled-task tracking
+across Debian/Raspbian hosts (ported from
+[Schedule Task Manager](../ScheduleTaskManager)). Looks and feels like a
+[Tabler](https://tabler.io) admin dashboard. Sign-in is delegated to
+Authentik (OIDC), with local admin/operator/viewer roles.
+
+## Status
+
+Built so far:
+
+- Monorepo scaffold, Tabler-themed app shell/navigation
+- Authentik OIDC login, roles (first user to sign in becomes admin), audit log
+- **Secrets** — expiry tracking for API tokens/certs/passwords
+- **IP Addresses (IPAM)** — inventory of IPs across vendors/locations
+
+Not yet built (see `.claude/plans` for the full delivery plan):
+
+- DNS management (Cloudflare/Loopia/Pi-hole/Azure/cPanel/Technitium)
+- Servers & scheduled task tracking (cron/systemd via agent)
+- Live integrations: Proxmox, Synology, Semaphore, Tailscale, Gitea, Dockhand
+
+## Requirements
+
+- Node.js 20+
+- An Authentik instance reachable from wherever this app runs
+
+## 1. Set up an Authentik application
+
+1. Create an **OAuth2/OpenID Provider**:
+   - Redirect URI: `<APP_BASE_URL>/auth/callback`
+   - Scopes: `openid`, `email`, `profile`
+2. Create an **Application** using that provider, and assign the users/groups
+   who should be able to sign in — Authentik controls who can authenticate;
+   the app's own admin/operator/viewer roles control what they can do once in.
+3. Copy the provider's issuer URL, client ID, and client secret into `.env`.
+
+## 2. Local development
+
+```bash
+cp .env.example .env   # fill in AUTHENTIK_*, SESSION_SECRET, CREDENTIALS_ENCRYPTION_KEY
+npm install
+npm run dev:server   # http://localhost:3000 (API)
+npm run dev:web      # http://localhost:5173 (Vite dev server, proxies /api and /auth to :3000)
+```
+
+Visit `http://localhost:5173` during development. Database migrations run
+automatically on server start. SQLite data lands in `./data` (gitignored).
+
+Generate `SESSION_SECRET` and `CREDENTIALS_ENCRYPTION_KEY` with:
+
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+## 3. Run with Docker
+
+```bash
+cp .env.example .env
+# edit .env
+docker compose -f docker-compose.dev.yml up -d --build   # build locally
+# or, once an image is published to your registry:
+docker compose up -d
+```
+
+The app listens on `HOST_PORT` (default `3000`); SQLite data persists in
+`./data` on the host.