Skip to content

Adding a Service

How to onboard a new Docker Compose service into the homelab monorepo so that Komodo deploys it automatically and Homepage picks up a tile.

Prerequisites

  • Docker and Docker Compose installed on the target host
  • The Traefik stack is running (it owns the traefik Docker network)
  • Komodo is running and connected to the host

Steps

1. Copy the template

cp -r services/_template services/<service-name>
cd services/<service-name>

2. Edit compose.yml

  • Replace all REPLACE_ME placeholders with real values
  • Set the correct image, container name, and ports
  • Configure Traefik labels with the desired subdomain (<name>.infra.realemail.app)
  • Add volumes for persistent data if needed
  • Ensure the service joins the traefik network (external)

3. Configure secrets

If the service needs secrets (API keys, passwords, DB credentials):

  1. Copy .env.sops.yaml.example to .env.sops.yaml and fill in real values
  2. Encrypt in WSL: sops -e -i services/<service-name>/.env.sops.yaml
  3. Commit and push the encrypted file
  4. On the host, decrypt SOPS YAML to a dotenv-format .env:
SOPS_AGE_KEY_FILE=/etc/homelab/age-key.txt sops -d .env.sops.yaml \
  | sed 's/: /=/' > .env

See secrets runbook for details on the YAML-to-dotenv conversion.

4. Update inventory (if applicable)

If this is a significant service that should appear in the inventory:

  1. Add an entry to the appropriate inventory file or create a new one
  2. Run generators to update downstream files:
uv run python inventory/generators/render-homepage.py
uv run python inventory/generators/render-doc-stubs.py

5. Update backup policy

Edit backup.yml in the service directory:

  • Set the correct tier (1 = critical, 2 = nice-to-have, 3 = replaceable)
  • List the paths that need backing up
  • Add pre/post hooks if the service needs to quiesce before backup

6. Write the README

Fill in the service README with:

  • What the service does
  • Quick reference table (image, port, URL)
  • Any manual setup steps
  • Troubleshooting tips

7. Commit and push

git add services/<service-name>
git commit -m "Add <service-name> service"
git push

Komodo detects the push (via webhook or polling) and deploys the stack automatically. The Homepage tile appears after the generator runs.

DNS

New services on infra-services use *.infra.realemail.app subdomains. Create a CNAME or A record pointing to 192.168.6.17 (or use Cloudflare DNS if the service should be publicly accessible with TLS).

Checklist

  • [ ] compose.yml has no REPLACE_ME placeholders
  • [ ] .env.sops.yaml is encrypted (pre-commit hook verifies this)
  • [ ] backup.yml tier is set correctly
  • [ ] README documents the service
  • [ ] Generators run cleanly (--check passes)
  • [ ] Service starts with docker compose up -d on the target host
  • [ ] Traefik routes traffic correctly to the service