# 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.