66 lines
1.7 KiB
Markdown
66 lines
1.7 KiB
Markdown
# 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.
|