Homelab-manager/README.md

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) and scheduled-task tracking across Debian/Raspbian hosts (ported from Schedule Task Manager). Looks and feels like a Tabler 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
• DNS — zone/record management across Cloudflare, Loopia, Pi-hole, Azure DNS, cPanel, and Technitium; providers are configured in-app (not via env vars) and their credentials are encrypted at rest
• Servers & Tasks — cron/systemd tracking across Debian/Raspbian servers via a lightweight push agent (agent/linux/), plus manual entries for things an agent can't see (Docker jobs, backups)
• Integrations → Tailscale — device list with online/authorized status, and authorize/deauthorize/remove actions; a live device-count widget on the Dashboard.
• Integrations → Gitea — repo list with each repo's last CI run status, and re-running just the failed jobs in a run; a live repo-count widget (with a failing-build warning) on the Dashboard.
• Integrations → Dockhand — container status across every Docker host Dockhand manages (one credential covers all of them), with start/stop/restart actions; a live running/total widget on the Dashboard.
• Integrations → Semaphore — Ansible run status per template across every project, with a "Run" action to trigger a template; a live template-count widget (with a last-failed warning) on the Dashboard.
• Integrations → Proxmox — VM/LXC status across every node in the cluster, with start/stop/restart actions; a live running/total widget on the Dashboard. Supports self-signed certificates (common in homelab Proxmox setups).

All five integrations follow the same config-in-UI + encrypted-credentials pattern as DNS providers, so the remaining one slots into the same "Add integration" form once built.

Not yet built (see .claude/plans for the full delivery plan):

• Remaining live integration: Synology

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

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:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

3. Run with Docker

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.