00de8107ea
public (wzorce/schematy, bez IP/portow/sciezek hostow): observer, capability-model, event-system, standards, agent-operating-procedures, service-model, action-approval-model. private: recon-multiagent, fleet-inventory, fleet-inventory-verify, kb-mail-pillar, kb-documents-pillar, topology, agent-system. deprecated (martwe stuby z 2026-04-15) — visibility private wg rozstrzygniecia 6: access-model, core-stack, legacy-services-list, networking. git mv + frontmatter, tresc nietknieta. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
85 lines
2.5 KiB
Markdown
85 lines
2.5 KiB
Markdown
---
|
|
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.
|