h5h Homelab

Appearance

Step-by-step Setup Guide ​

Prerequisites ​

  • Docker Desktop (or OrbStack for lower RAM usage on Mac)
  • Domain h5h.me pointed to Cloudflare (free plan)
  • A Cloudflare API token with Zone:DNS:Edit
  • A Tailscale account

1. Clone & run first-time setup ​

bash
git clone https://github.com/nichehemanth/h5h.git ~/Desktop/hemanth/h5h
cd ~/Desktop/hemanth/h5h/code
make init

make init runs scripts/setup.sh which:

  1. Copies .env.example → docker/.env
  2. Creates all data/ subdirectories
  3. Generates random secrets via scripts/generate-secrets.sh
  4. Installs npm dependencies

2. Create Cloudflare Tunnel ​

By providing CF_API_TOKEN, CF_ACCOUNT_ID, and CF_ZONE_ID in your docker/.env, you can create the entire tunnel, ingress rules, and complete DNS routing for all subdomains instantly:

bash
make setup-tunnel

NOTE

This script will automatically inject the generated CF_TUNNEL_TOKEN back into your .env file for you. You don't need to hunt for the token or paste it manually!

3. Fill in secrets ​

bash
$EDITOR docker/.env

Ensure tokens like GOOGLE_CLIENT_ID, TS_AUTHKEY, and specific application passwords are populated.

4. Start Core Infrastructure ​

bash
# Start Traefik + Authentik + Dashboard + Cloudflare Tunnel
make core

# Configure Role-Based Access Control and Google Sign-in automatically
make setup-authentik

NOTE

make setup-authentik can take up to ~60 seconds the first time. setup_rbac.py polls the Authentik "Embedded Outpost" for up to 12 × 5 s before it can create proxy providers. If you see Waiting for Authentik background workers to generate embedded outposts…, that's expected — don't abort. Re-running the command is safe (every step is idempotent via get_or_create).

NOTE

Older docs (docker/cloudflared/SETUP.md) describe manual Cloudflare tunnel setup. That path still works but is deprecated — make setup-tunnel now provisions the tunnel, ingress, DNS CNAMEs, and writes CF_TUNNEL_TOKEN back to .env for you.

5. Configure Specific Applications ​

Dashboard (make core) ​

Connect Homepage (sh.h5h.me) widgets to respective service APIs within HOMEPAGE_VAR_* .env variables.

Tailscale VPN (make vpn) ​

  • Mesh VPN using WireGuard. Advertises the Docker network as a subnet route, so devices can reach services directly.

Security Stack (make security) ​

  • Starts CrowdSec (intrusion detection), Traefik bouncer, Loki, and Promtail. Make sure to generate the bouncer API key by running docker exec h5h_crowdsec cscli bouncers add traefik-bouncer and adding it to .env.

Media Pipeline (make plex) ​

  1. Visit https://plex.h5h.me mapping movies/tv/music to the data/plex/ directories.
  2. Initialize and secure the qBittorrent VueTorrent client via ./scripts/setup-qbittorrent.sh. Downloads map straight to Plex via data/torrent/.

Updates & Rollbacks (Time-Travel) ​

This homelab is designed for lazy, zero-maintenance updates with a 100% reliable instant rollback button.

How to Update ​

Just run the update command:

bash
make update
  • What happens: The system automatically captures a snapshot of the exact image versions (sha256 digests) currently running across all your containers and saves them permanently in docker/versions.json (tracked in Git). Then, it pulls the newest :latest images and restarts your containers.

How to Roll Back ​

If an update breaks a container (even if you discover it months later), you can instantly time-travel that container back to any previous working state.

To roll back a specific service (e.g., Plex):

bash
make rollback s=plex
  1. You will be presented with a history of every version Plex has run on, complete with dates.
  2. Type the number of the snapshot you want to restore.
  3. The system will instantly restart Plex using that exact known-good image digest!

To roll back ALL services:

bash
make rollback
  1. You will see a list of dates when global updates were performed.
  2. Select a date, and the entire homelab will time-travel back to the exact image digests running on that day.

Immich Mobile App (make photos) ​

Install the Immich app. Server: https://photos.h5h.me. Enable Auto Backup.

Nextcloud Sync (make drive) ​

Install Nextcloud desktop clients and link against https://drive.h5h.me.

MIT License

h5h homelab