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/:

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

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.

2.4 KiB Raw Blame History