---
okf: "0.1"
type: subsystem
visibility: private
status: active
updated: 2026-05-11
links:
  - ../runbooks/service-operational-recovery.md
---

# Service Lifecycle and Recovery

This document defines the lifecycle of a service in the homelab and the procedures for operational recovery.

## Service Lifecycle

1.  **Onboarding**: 
    - Create `services/<service>/` directory.
    - Define `docker-compose.yml`, `service.yaml`, `README.md`, `env.example`, and `healthcheck.sh`.
    - Register service in `inventory/topology.yaml` or relevant host configs.
2.  **Provisioning**:
    - Ensure `/opt/homelab/data/<service>` exists.
    - Ensure `/opt/homelab/config/<service>` exists and contains required secrets/configs.
    - Setup environment variables from `env.example` into `/opt/homelab/config/<service>/.env`.
3.  **Deployment**:
    - `scripts/deploy/deploy.sh` (Starts fresh)
    - `scripts/deploy/deploy.sh --resume` (Continues after interruption)
4.  **Verification**:
    - Automatic as part of the `deploy.sh` pipeline (`verify` stage).
    - Manual: `scripts/deploy/deploy.sh --stage verify`.
5.  **Maintenance**:
    - Periodic updates via `docker compose pull`.
    - Log monitoring via `docker compose logs -f`.
6.  **Decommissioning**:
    - `docker compose down`.
    - Archive `/opt/homelab/data/<service>` if necessary.

## Persistent Data Conventions

- **Data**: `/opt/homelab/data/<service>` - Primary persistent state.
- **Config**: `/opt/homelab/config/<service>` - Local overrides and secrets.
- **Backups**: Standard backup routines should target `/opt/homelab/data/`.