homelab-starter

One command. Pick your apps. Walk away with a working home server.

Homelab Starter sets up your home server so you can run your own apps — password manager, media server, photo backup, smart home hub, and more — without any technical knowledge required.

Answer a few questions, pick the apps you want from a menu, and it handles everything else: installing the software it needs, creating secure passwords automatically, and getting your apps running. No config files to edit. No guides to read. No passwords to copy-paste.

Quick start

Option A — one-liner (no Python required):

curl -fsSL https://raw.githubusercontent.com/moooosik/homelab-starter/main/install.sh | bash

Option B — pip:

pip install homelab-starter
homelab-starter

Either way: it checks what your server needs, installs anything missing, then walks you through the setup.

What happens when you run it

1.  Checks Docker is installed
      → If not: offers to install it automatically via get.docker.com
      → Adds your user to the docker group (no logout needed)

2.  Detects your server's local IP (e.g. 192.168.0.101)

3.  Asks your configuration depth:
      basic    — sensible defaults for everything, just pick apps
      guided   — prompts for passwords, file paths, and tokens
      advanced — all options exposed

4.  Shows a scrollable app checklist
      ↑↓ to navigate · Space to select · Enter to confirm

5.  Offers Caddy (reverse proxy) with a plain-English explanation
      → If you say yes, generates a Caddyfile automatically

6.  Asks if you have a custom domain
      → If yes: prints port-forwarding instructions + CrowdSec setup guide

7.  For guided/advanced: prompts for config specific to selected apps
      (media paths, admin passwords, API tokens)

8.  Generates ~/homelab-starter/docker-compose.yml + .env
      → Passwords and secret keys are cryptographically generated
      → You never need to touch the .env manually

9.  Runs: docker compose up -d --pull always

10. Prints the URL for every installed service

11. If Homepage was selected: prints the dashboard URL on its own line
      → "Bookmark this — it's your homelab home page."

App catalog

61 apps across 13 categories. Every app ships with a pre-configured compose snippet — ports, volumes, environment variables, and restart policies all set. The installer walks you through categories one at a time so you're never staring at a wall of 61 choices.

Your Digital Life

Media

Media Automation

AI

Smart Home

Networking

Security

Documents

Productivity

Communication

Monitoring

Management

Maintenance

Configuration modes

Basic

Uses defaults for everything. Recommended for first-timers who just want to get running.

• No questions asked beyond the app checklist
• All passwords auto-generated
• All data stored under Docker named volumes

Guided (default)

Prompts for the important stuff — file paths, admin passwords, API keys — and uses defaults for the rest. The right choice for most people.

Example prompts:

  Path to your media library [/mnt/media]: /data/movies
  Nextcloud admin password: ••••••••
  Tailscale auth key (from tailscale.com/settings/keys): tskey-auth-...

Advanced

Exposes every configurable option. For users who want full control over every volume path and environment variable.

Auto-generated secrets

homelab-starter uses Python's secrets module to generate cryptographically secure passwords for every app that needs one. You never have to create or remember these — they live in ~/homelab-starter/.env.

Apps that get auto-generated secrets:

• Immich database password
• Nextcloud database + admin password (if not provided in guided mode)
• Paperless-ngx database password, secret key, and admin password
• Authentik database password and secret key
• Gitea, BookStack, Vikunja, Planka, Miniflux, Mattermost — database passwords
• Grafana admin password, Healthchecks secret key
• Hoarder and Matrix registration secrets
• Pi-hole web admin password
• NAS Bundle (Samba) share password
• Flowise admin password

Watchtower — automatic updates

Watchtower is always included. It checks for new container image versions every night at 4 AM and updates them automatically.

Apps excluded from auto-update (they require manual migration steps on major version bumps):

To update an excluded app safely:

cd ~/homelab-starter
docker compose pull <service-name>
docker compose up -d <service-name>
# run any migration steps listed in the app's changelog

Custom domain setup

When the installer asks "Do you have a custom domain?", answering yes triggers:

1. Port forwarding instructions — forward ports 80 and 443 from your router to the server IP
2. DNS instructions — point your domain (and *.domain) to your public IP
3. Caddyfile generation — pre-populated with subdomains for each selected app
4. CrowdSec guide — how to wire the CrowdSec bouncer to Caddy to block bad actors

If you don't have a domain, all apps are still accessible by local IP (e.g. http://192.168.0.101:8096 for Jellyfin).

CLI flags

homelab-starter           # full interactive install
homelab-starter --dry-run # generate files but do not deploy
homelab-starter --update  # re-generate files from existing .env (no prompts)
homelab-starter --list    # browse all 61 available apps and exit

--update is useful after pulling a new version of homelab-starter — it re-reads your existing ~/homelab-starter/.env, detects which apps are installed from the current docker-compose.yml, regenerates everything with the latest config (new healthchecks, env vars, side files), and restarts your containers. Your secrets are preserved.

--list works without Docker installed — useful for browsing the catalog on any machine before committing to a server.

Deploy directory

Everything lives in ~/homelab-starter/ on your server:

~/homelab-starter/
├── docker-compose.yml   ← merged config for all selected apps
├── .env                 ← all secrets and config values — keep this private
├── Caddyfile            ← generated if Caddy was selected
└── CONNECT.md           ← per-app instructions for clients, mobile apps, and devices

To re-generate after updating homelab-starter:

homelab-starter --update

Requirements

Tested on: Ubuntu 22.04, Ubuntu 24.04, Debian 12, Raspberry Pi OS (64-bit)

Uninstalling

To stop everything:

cd ~/homelab-starter
docker compose down

To remove all data (destructive — this deletes your app data):

cd ~/homelab-starter
docker compose down -v
rm -rf ~/homelab-starter

vs. alternatives

Support

If homelab-starter saved you an afternoon of config-file wrestling, a coffee goes a long way:

Contributing

Bug reports and app addition requests welcome — open an issue.

To add a new app, add an entry to homelab/apps.py following the existing pattern (services dict + volumes dict + optional guided_prompts).

License

MIT — do whatever you want with it.