New Service Onboarding Runbook

Follow this runbook every time a new service is added to the homelab. No service goes live without completing this checklist.

---

Pre-Deployment Checklist

• Service has a defined purpose
• Port confirmed not in use: ss -tulnp | grep <PORT>
• Docker Compose file created in ~/stacks/apps/<service-name>/
• .env file created for secrets — never hardcoded in compose file
• Backup path identified
• Reverse proxy entry planned (NPM)
• DNS entry planned (Pi-hole)
• Uptime Kuma monitor planned

---

Step 1 — Create the Compose File

mkdir -p ~/stacks/apps/<service-name>
cd ~/stacks/apps/<service-name>
nano docker-compose.yml

Minimum template:

services:
  <service-name>:
    image: <image>:latest
    container_name: <service-name>
    restart: unless-stopped
    ports:
      - "<host-port>:<container-port>"
    volumes:
      - <service-name>_data:/data
    env_file:
      - .env
volumes:
  <service-name>_data:

---

Step 2 — Create the .env File

nano .env
chmod 600 .env

---

Step 3 — Deploy

docker compose up -d
docker logs <service-name> --follow
docker ps | grep <service-name>

---

Step 4 — Reverse Proxy (Nginx Proxy Manager)

1. NPM → Proxy Hosts → Add Proxy Host
2. Domain: <service>.home.lab
3. Forward: host01 → <container-port>

---

Step 5 — DNS Record (Pi-hole)

1. Pi-hole → Local DNS → DNS Records → Add
2. Domain: <service>.home.lab → IP: 192.168.20.x

---

Step 6 — Uptime Kuma Monitor

1. Add Monitor → HTTP(s)
2. URL: http://<service>.home.lab
3. Interval: 60s

---

Step 7 — Update Documentation

• Add to Inventory
• Add to Docker Stacks if non-trivial
• Add DNS record to Networking
• Add Prometheus scrape target if metrics are exposed

---

Done

Service is live, monitored, and documented.