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>
92 lines
3.3 KiB
Markdown
92 lines
3.3 KiB
Markdown
---
|
|
okf: "0.1"
|
|
type: subsystem
|
|
visibility: public
|
|
status: active
|
|
updated: 2026-05-20
|
|
links: []
|
|
---
|
|
|
|
# Infrastructure Standards
|
|
|
|
This document defines the standards and conventions for the homelab GitOps-lite environment.
|
|
|
|
## Host Architecture
|
|
|
|
| Host | Role | Description |
|
|
|------|------|-------------|
|
|
| **SATURN** | Primary Node | Development, orchestration, and git source of truth (commit node). |
|
|
| **SOLARIA** | Compute Node | GPU, inference, and heavy compute workloads. |
|
|
| **PIHA** | Infra Node | Core infrastructure services, automation, and monitoring. |
|
|
| **VPS** | Edge Node | Public ingress, reverse proxy, and edge services. |
|
|
|
|
## Directory Layout
|
|
|
|
### Repository Layout
|
|
|
|
```text
|
|
/
|
|
├── docs/ # Infrastructure documentation
|
|
├── hosts/ # Host-specific configurations
|
|
├── inventory/ # Topology and templates
|
|
├── services/ # Normalized service definitions
|
|
│ └── <service>/
|
|
│ ├── docker-compose.yml
|
|
│ ├── service.yaml
|
|
│ ├── README.md
|
|
│ ├── env.example
|
|
│ └── healthcheck.sh
|
|
├── scripts/ # Management and deployment scripts
|
|
└── README.md
|
|
```
|
|
|
|
### Runtime Layout (on Execution Nodes)
|
|
|
|
Runtime state must live outside the repository to keep it immutable and clean.
|
|
|
|
```text
|
|
/opt/homelab/
|
|
├── services/ # Active docker-compose files (deployed from git)
|
|
├── data/ # Persistent volume data (backed up)
|
|
├── config/ # Host-local overrides and secrets (not in git)
|
|
│ └── <service>/
|
|
│ ├── .env # Merged environment variables
|
|
│ └── overrides/ # Local configuration overrides
|
|
└── logs/ # Service logs
|
|
```
|
|
|
|
## Service Standards
|
|
|
|
1. **Normalization**: Every service MUST follow the `services/<service>/` layout.
|
|
2. **Metadata**: Every service MUST have a `service.yaml` defining its operational contract. This is the primary source of truth for AI agents.
|
|
3. **Healthchecks**: Every service MUST have a `healthcheck.sh` for verification. Agents use this to emit stability events.
|
|
4. **Actionability**: Any automated recovery action proposed by an agent must be backed by a `service.yaml` definition.
|
|
5. **Secrets**: NEVER commit secrets to Git. Use `env.example` as a template and populate `/opt/homelab/config/<service>/.env` on the host. Agents must treat these as "black box" configurations.
|
|
|
|
## Docker Compose Standards
|
|
|
|
1. **File Naming**: Use `docker-compose.yml`.
|
|
2. **Container Naming**: Match the service name.
|
|
3. **Restarts**: Always use `restart: unless-stopped` unless specified otherwise in `service.yaml`.
|
|
4. **Networking**:
|
|
- Use `tailscale` internal mesh for inter-host communication.
|
|
- Expose ports only when necessary.
|
|
5. **Volumes**: Use absolute paths to `/opt/homelab/data/<service>`.
|
|
|
|
## Environment Variables
|
|
|
|
- `.env`: Default environment variables (checked into git if safe).
|
|
- `.env.local`: Host-specific overrides (not in git).
|
|
|
|
## Naming Conventions
|
|
|
|
- Hosts: All caps (SATURN, SOLARIA, PIHA, VPS).
|
|
- Services: Kebab-case (e.g., `ollama-server`).
|
|
- Containers: Match service name.
|
|
|
|
## Deployment Flow
|
|
|
|
1. Changes are committed and pushed to **SATURN**.
|
|
2. Execution nodes (SOLARIA, PIHA, VPS) pull changes.
|
|
3. Deployment scripts trigger `docker compose up -d`.
|