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

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

• 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

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.