homelab-optimized/docs/runbooks/add-new-service.md

Add New Service Runbook

This runbook walks through a clean, tested path for adding a new service to the homelab using GitOps with Portainer.

⚠️ Prerequisites: CI runner access, SSH to target hosts, SSO admin privilege.

1. Prepare Compose File

# Generate a minimal stack template
../scripts/ci/workflows/gen-template.py --service myservice

Adjust docker-compose.yml:

• Image name
• Ports
• Environment variables
• Health‑check

2. Validate Configuration

docker compose -f docker-compose.yml config > /tmp/merged.yml
# Validate against OpenAPI specs if needed

3. Commit Locally

git add docker/compose/*.yml
git commit -m "Add myservice stack"

4. Push to Remote & Trigger GitOps

git push origin main

The Portainer EE GitOps agent will automatically deploy. Monitor the stack via the Portainer UI or portainer api.

5. Post‑Deployment Verification

Check	Command	Expected Result
Service Running	docker ps --filter "name=myservice"	One container running
Health Endpoint	curl http://localhost:8080/health	200 OK
Logs	docker logs myservice	No fatal errors

6. Update Documentation

1. Add entry to docs/services/VERIFIED_SERVICE_INVENTORY.md.
2. Create a quick‑start guide in docs/services/<service>/README.md.
3. Publish to the shared wiki.

7. Optional – Terraform Sync

If the service also needs infra changes (e.g., new VM), update the Terraform modules under infra/ and run terragrunt run-all apply.

---

Gotchas –

• Race conditions: rebasing before push.
• Health‑check failures: check Portainer Events.
• Secrets: use Vault and reference in secrets section.