homelab-compose

A collection of Docker Compose stacks for self-hosted services. Each service lives in its own folder with a compose.yml (the service definition) and an example.env (a template for all the settings you need to fill in).

This guide assumes you're starting from scratch — no Linux, Docker, or Git experience required.

---

Step 1 — Install Docker

Docker is the software that runs all the services in this repo. You need Docker Engine (the core) and the Compose plugin (which reads compose.yml files).

Follow the official instructions for your operating system:

• Linux (recommended for a home server): https://docs.docker.com/engine/install/
• Mac or Windows (for local testing): https://docs.docker.com/desktop/

After installing, verify it's working by opening a terminal and running:

docker --version
docker compose version

Both commands should print a version number. If you see "command not found", Docker isn't installed correctly — revisit the install guide.

What is a terminal? On Linux: look for an app called Terminal, Konsole, or similar. On Mac: search for Terminal in Spotlight (Cmd+Space). On Windows: use PowerShell or Windows Terminal (not Command Prompt).

---

Step 2 — Install Git

Git is used to download this repo and keep it up to date.

Check if you already have it:

git --version

If not, install it:

• Linux (Debian/Ubuntu): sudo apt install git
• Linux (RHEL/Fedora): sudo dnf install git
• Mac: xcode-select --install
• Windows: Download from https://git-scm.com/downloads

---

Step 3 — Download this repo

Navigate to the folder where you want to keep this on your machine, then clone the repo:

git clone https://github.com/darkiris4/homelab-compose.git
cd homelab-compose

What does this do? git clone downloads a copy of everything in this repo to your computer. cd homelab-compose moves you into the downloaded folder so you can work inside it.

---

Step 4 — Create the shared Docker networks

Most stacks in this repo expect two Docker networks to already exist. You only need to do this once per machine:

docker network create frontend
docker network create backend

• frontend — for services that are exposed to your browser through the reverse proxy (Traefik)
• backend — for internal services like databases that shouldn't be directly reachable

What is a Docker network? It's a private virtual network that lets containers talk to each other. By using shared networks, any container on frontend can reach any other container on frontend, even if they're in different stacks.

---

Step 5 — Start with Traefik (if you want HTTPS and subdomains)

Traefik acts as the front door for all your other services. It handles HTTPS certificates automatically and routes traffic like sonarr.yourdomain.com to the right container.

If you don't need HTTPS or subdomain routing yet, you can skip this and access services directly on their port numbers (e.g. http://192.168.1.100:8989 for Sonarr).

To set up Traefik, see the traefik/ section below and follow the steps there first before starting anything else.

---

Step 6 — Deploy a service

Every service follows the same pattern. Using Sonarr (inside the servarr stack) as an example:

1. Go into the stack's folder

cd servarr

2. Copy the example env file

cp example.env .env

This creates your personal settings file. The example.env is a template — you'll fill in your real values in .env. Never edit example.env directly.

3. Edit your settings

Open .env in a text editor:

nano .env

nano basics:

• Arrow keys to move around
• Type to edit
• Ctrl+O then Enter to save
• Ctrl+X to exit

Replace all the placeholder values with your real settings. Every variable has a comment above it explaining what it does. Look for things like:

• changeme — replace with a real password
• your-secret-key — replace with a long random string (you can generate one with openssl rand -hex 32)
• yourdomain.example.com — replace with your actual domain
• /docker-data/... — these are paths on your host machine where data will be saved; change them to wherever you want to store data

4. Start the stack

docker compose up -d

What does -d mean? It stands for "detached" — the containers run in the background so you get your terminal prompt back. Without it, the logs stream directly to your terminal and pressing Ctrl+C would stop everything.

5. Check that it's running

docker compose ps

You should see your containers listed with a status of running or healthy. If any show exited, something went wrong — check the logs.

6. View the logs

docker compose logs -f

This streams the live log output from all containers in the stack. Press Ctrl+C to stop watching (the containers keep running).

To see logs from just one container:

docker compose logs -f sonarr

7. Stop the stack

docker compose down

This stops and removes the containers. Your data is safe — it stays in the folders you configured in .env.

---

Keeping things up to date

To pull the latest changes to this repo:

git pull

To update a running stack to the latest container images:

docker compose pull
docker compose up -d

---

Common problems

"network frontend not found" or "network backend not found" You skipped Step 4. Run the docker network create commands and try again.

Container exits immediately after starting Check the logs: docker compose logs. Usually this means a required variable in .env is missing or wrong.

Port already in use Another service on your machine is already using that port. Change the *_PORT variable in .env to a different number and run docker compose up -d again.

Permission denied on a folder Docker is trying to write to a path that your user doesn't own. Run sudo chown -R $USER:$USER /path/to/folder on the affected directory.

---

Stacks

Reverse proxy & networking

Directory	What it is	Links
traefik	Reverse proxy that handles HTTPS (via Let's Encrypt) and routes traffic to your other services by subdomain. Start this first if you want HTTPS.	GitHub · Docs
netbird	WireGuard-based mesh VPN — lets your devices connect to each other securely across the internet without opening firewall ports.	GitHub · Docs

Media

Directory	What it is	Links
plex-tautulli	Plex media server + Tautulli (watch history stats and notifications).	Plex: GitHub · Docs Tautulli: GitHub · Docs
jelly-stuffs	Jellyfin media server + Jellystat (watch history stats).	Jellyfin: GitHub · Docs Jellystat: GitHub
servarr	The "arr" stack: Sonarr (TV), Radarr (movies), Prowlarr (indexer manager), and Jackett (indexer proxy). Automates finding and downloading media.	Sonarr: GitHub · Docs Radarr: GitHub · Docs Prowlarr: GitHub · Docs Jackett: GitHub · Docs
download-clients	qBittorrent and SABnzbd behind a Gluetun VPN container so all download traffic goes through your VPN.	qBittorrent: GitHub · Docs SABnzbd: GitHub · Docs Gluetun: GitHub · Docs
overseerr	Request management for Plex — lets users browse and request movies/shows.	GitHub · Docs
seerr	Media request management for Jellyfin, Plex, and Emby — lets users browse and request movies/shows.	GitHub · Docs
unmanic	Automatically converts media files in your library to target codecs/formats (e.g. H.265, Opus).	GitHub · Docs

Streaming

Directory	What it is	Links
restreamer	Takes a live video input (RTMP, SRT, webcam, etc.) and restreams it to other destinations or serves it as HLS.	GitHub · Docs
retro-streamer	Streams RetroArch and Dolphin (GameCube/Wii emulator) over a browser-accessible interface.	RetroArch: GitHub · Docs Dolphin: GitHub · Docs
wyze-bridge	Exposes Wyze cameras as RTSP streams so they work with any NVR or HomeKit.	GitHub
open-speedtest	Local network speed test server — like fast.com but self-hosted.	GitHub · Site

Monitoring & dashboards

Directory	What it is	Links
uptime-kuma	Monitors your services and websites and alerts you when something goes down.	GitHub
homepage	A customizable start page that shows all your services, system stats, and widgets in one place.	GitHub · Docs
librenms	Full network monitoring via SNMP — tracks bandwidth, device health, and alerting for your network gear.	GitHub · Docs

Authentication

Directory	What it is	Links
authentik	Identity provider and SSO — adds login/2FA in front of any service, and provides OAuth2/SAML for apps that support it.	GitHub · Docs

Dev & infrastructure

Directory	What it is	Links
gitlab	Self-hosted Git with CI/CD, container registry, and issue tracking.	GitLab · Docs
dockge	Web UI for managing all your Docker Compose stacks from a browser.	GitHub
dockhand	Automation tool for keeping Docker containers up to date and in sync with git.	GitHub
nexterm	Web-based SSH and terminal client — connect to your servers from a browser.	GitHub · Site
networktoolshub	Browser-based network utility toolkit (ping, traceroute, DNS lookup, etc.).	Custom image
open-webui	Web interface for running local LLMs via Ollama.	GitHub · Docs

Smart home

Directory	What it is	Links
homebridge	Bridges non-HomeKit smart home devices into Apple HomeKit.	GitHub · Docs
scrypted	Integrates cameras and smart devices into HomeKit, Google Home, and Alexa with hardware transcoding support.	GitHub · Docs

Gaming

Directory	What it is	Links
minecraft	Minecraft Java Edition server (runs Paper by default).	GitHub · Docs
minecraft-bedrock	Minecraft Bedrock Edition server (for console/mobile players).	GitHub

Virtual machines

Directory	What it is	Links
windows11	Windows 11 running inside Docker — accessible via browser (noVNC) or RDP.	GitHub
tiny11	A stripped-down Windows image (Tiny11) in Docker, same access methods as above.	GitHub

Misc

Directory	What it is	Links
fileserver	Simple static file server.	GitHub · Docs
rustdesk	Self-hosted remote desktop server (alternative to TeamViewer/AnyDesk).	GitHub · Docs
tvtv2xmltv	Fetches TV guide data from TVTV and converts it to XMLTV format for use with Jellyfin, Plex, or a DVR.	Custom image

---

How this repo is structured

homelab-compose/
├── traefik/
│   ├── compose.yml      ← defines the containers and how they're configured
│   ├── example.env      ← template showing all variables with descriptions
│   └── traefik.yml      ← static Traefik config (some stacks have extra config files)
├── servarr/
│   ├── compose.yml
│   └── example.env
└── ...one folder per service

A few things to know:

• compose.yml — the service definition. You generally don't need to edit this.
• example.env — a template. Copy it to .env and fill in your values. Never commit your .env to a public git repo — it contains passwords and keys.
• Persistent data is stored on your host machine at /docker-data/<stack-name>/ by default. You can change this in .env. This is where your databases, configs, and media library paths live — separate from the containers so data survives container updates.
• Ports — all host-side port numbers are set in .env. If something conflicts with another service, just change the port number there and restart.