homelab-codex-ws/kb/subsystems/service-model.md

---
okf: "0.1"
type: subsystem
visibility: public
status: active
updated: 2026-05-11
links: []
---

# Service Model and Healthchecks

This document defines the normalized service model for the homelab.

## Service Layout

Each service must reside in its own directory under `services/`:

```text
services/<service>/
├── docker-compose.yml   # Docker Compose definition
├── service.yaml         # Service metadata and orchestration contract
├── README.md            # Service documentation
├── env.example          # Template for required environment variables
└── healthcheck.sh       # Standardized healthcheck script
```

## Service Metadata (`service.yaml`)

The `service.yaml` file provides a machine-readable contract for deployment and orchestration.

### Schema

```yaml
service:
  name: <string>               # Canonical service name (kebab-case)
  owner_node: <string>         # Preferred host node
  exposure: <class>            # public, private, or local-only
  dependencies: [<service>]    # List of required services
  ports:
    - container: <int>
      host: <int>
      protocol: <tcp|udp>
  healthcheck:
    type: <string>             # local-only, container, http, mqtt
    endpoint: <string>         # URL or topic if applicable
    interval: <duration>
    timeout: <duration>
    retries: <int>
  restart_policy: <string>     # unless-stopped, always, etc.
  persistence:
    paths:
      - /opt/homelab/data/<service>/...
  runtime:
    directories: [<string>]    # Required host directories to be created
    env_vars: [<string>]       # List of required environment variables (keys only)
```

## Healthcheck Semantics

The `healthcheck.sh` script should return `0` for healthy and `1` for unhealthy. It should support different modes based on `service.yaml` definitions.

### 1. Local-only
Checks if the container is running and the process is alive within the host.

### 2. Container-level
Uses `docker inspect` or `docker exec` to check internal container health.

### 3. HTTP
Performs a `curl` against a specific endpoint (e.g., `/health` or `/`).

### 4. MQTT
Verifies that a specific topic is being updated or responds to a ping.

### 5. Dependency-aware
The healthcheck script may optionally check if its dependencies are healthy before reporting its own status.

## Runtime Authority

`/opt/homelab/config/<service>` is the source of truth for:
- Secrets (not in Git)
- Host-local overrides
- Mutable configuration

Services should mount files from this directory as needed.