oskar 00de8107ea feat(kb): przenosiny type=subsystem do kb/subsystems/ (18 plikow, bez SPLIT)

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>

2026-08-04 16:58:04 +02:00

2.5 KiB

Raw Blame History

okf

type

visibility

status

updated

links

0.1

subsystem

public

active

2026-05-11

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.5 KiB Raw Blame History