Sanitized mirror from private repository - 2026-04-06 10:21:40 UTC

docs/runbooks/add-new-service.md

@@ -0,0 +1,65 @@
+# 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
+
+```bash
+# 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
+
+```bash
+docker compose -f docker-compose.yml config > /tmp/merged.yml
+# Validate against OpenAPI specs if needed
+```
+
+## 3. Commit Locally
+
+```bash
+git add docker/compose/*.yml
+git commit -m "Add myservice stack"
+```
+
+## 4. Push to Remote & Trigger GitOps
+
+```bash
+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.