Homelab Hub

A self-hosted web app for managing a homelab: a central inventory and changelog instead of scattered notes.

Features

• Networks / IPAM — zones (WAN/GREEN/BLUE/ORANGE) with a color-coded IP map per subnet (gateway / used / reserved / free).
• Hosts — Proxmox servers, routers, firewalls — with a hypervisor field (proxmox / esxi / kvm / docker / none).
• VMs / Containers — with IP, zone, project, status and expiry date.
• Projects — group resources and track cleanup.
• Credentials — stored with AES-256-GCM encryption, revealed on demand.
• Changelog — every mutation is logged automatically (before/after) + manual entries.
• Services — catalog of URLs and ports.
• DNS & Domains — internal/external domains and DNS records.
• Exposures — how services are reached from the internet (reverse proxy / port forward / tunnel).
• Zone policy — firewall access matrix between zones.
• Topology — interfaces and links with per-service "path to internet" tracing.
• Proxmox sync — import VMs/containers and IPs from the Proxmox API.
• Global search, sample data, and an onboarding guide.

Tech stack

Next.js 16 (App Router) · TypeScript · Prisma + SQLite · Tailwind v4 · AES-256-GCM.

Run locally (development)

npm install
cp .env.example .env        # fill in the values (or generate them below)
npx prisma migrate dev      # creates the database and runs the seed
npm run dev                 # http://localhost:3000

Generate secrets:

openssl rand -hex 32   # for SESSION_SECRET and ENCRYPTION_KEY

Deploy

Option 1: Docker Compose (easiest)

openssl rand -hex 32   # twice (SESSION_SECRET + ENCRYPTION_KEY)
# edit docker-compose.yml and fill in the values
docker compose pull    # pulls git.majlis7.net/debe/homelab-hub:latest
docker compose up -d

Opens on http://<ip>:3000. The database is persisted in ./data. The image is built and published automatically by the CI on every push to main and on every version tag.

Option 2: LXC / systemd

npm ci
npm run build
# create a systemd unit running:
#   npx prisma migrate deploy && npx prisma db seed && npm run start

Example homelab-hub.service:

[Unit]
Description=Homelab Hub
After=network.target

[Service]
WorkingDirectory=/opt/homelab-hub
EnvironmentFile=/opt/homelab-hub/.env
ExecStart=/usr/bin/npm run start
Restart=always

[Install]
WantedBy=multi-user.target

Proxmox sync

1. In Proxmox: Datacenter → Permissions → API Tokens → Add (e.g. homelab@pam!sync).
2. Copy the secret.
3. In the app: Hosts → edit a Proxmox node → fill in:
   • API URL: https://<node-ip>:8006
   • Token ID: homelab@pam!sync
   • Token Secret: (encrypted automatically)
4. Settings → Hypervisor sync → Sync now.

Note: the host name must match the Proxmox node name.

Environment variables

Variable	Description
DATABASE_URL	SQLite path (relative to prisma/ or absolute like file:/data/homelab.db)
SESSION_SECRET	Session signing secret (64 hex)
ENCRYPTION_KEY	AES-256-GCM key for credentials (64 hex)
ADMIN_USERNAME / ADMIN_PASSWORD	Initial admin account (used on first seed)

Backup

Back up the database file and the secret key:

• Local: prisma/homelab.db + data/encryption.key (if present) + .env
• Docker: ./data + the env vars (ENCRYPTION_KEY / SESSION_SECRET)

⚠️ Losing ENCRYPTION_KEY means permanently losing access to stored credentials — keep a safe copy.

CI

Forgejo Actions runs the QA suite (npm run test:qa) and the production build on every push. See .forgejo/workflows/ci.yml.