506 lines
14 KiB
Markdown
506 lines
14 KiB
Markdown
# Service Catalog
|
|
|
|
> Complete service documentation with core options, feature integrations, and smart defaults
|
|
>
|
|
> Generated on: Wed, 30 Jul 2025 02:30:36 +0200
|
|
|
|
This document provides comprehensive documentation for homelab services, organized by:
|
|
- **Core Service Options**: The main service configuration
|
|
- **Feature Integrations**: Available monitoring, logging, and proxy features
|
|
- **Service Defaults**: What this service configures by default for each feature
|
|
|
|
## Overview
|
|
|
|
**Total Available Services:** 5
|
|
|
|
## Service Integration Matrix
|
|
|
|
| Service | Core Options | Monitoring | Logging | Proxy | Deployments |
|
|
|---------|--------------|------------|---------|-------|-------------|
|
|
| `example` | 5 | 📊 | 📝 | 🔀 | 0 |
|
|
| `gatus` | 11 | 📊 | 📝 | 🔀 | 1 |
|
|
| `grafana` | 3 | 📊 | 📝 | 🔀 | 1 |
|
|
| `minio` | 4 | ❌ | ❌ | ❌ | 1 |
|
|
| `prometheus` | 12 | 📊 | 📝 | 🔀 | 1 |
|
|
|
|
**Legend:** 📊📝🔀 = Feature available, ❌ = Feature not available
|
|
|
|
## Service Documentation
|
|
|
|
### example
|
|
|
|
**Deployment Status:** 0/2 nodes have this service enabled
|
|
|
|
#### Core Service Options
|
|
|
|
The main configuration options for example:
|
|
|
|
```nix
|
|
homelab.services.example = {
|
|
description = Example Homelab Service; # No description
|
|
enable = false; # Whether to enable Example Homelab Service.
|
|
openFirewall = true; # Whether to open the ports specified in `port` and `webPort` in the firewall.
|
|
port = 1234; # No description
|
|
systemdServices = [
|
|
"example.service",
|
|
"example"
|
|
]; # Systemd services to monitor
|
|
};
|
|
```
|
|
|
|
#### Feature Integrations
|
|
|
|
##### 📊 Monitoring Integration
|
|
|
|
Available monitoring options:
|
|
|
|
```nix
|
|
homelab.services.example = {
|
|
# ... core options above ...
|
|
|
|
monitoring.enable = true; # Enable monitoring for example
|
|
monitoring.extraLabels = {}; # No description
|
|
monitoring.healthCheck.conditions = [
|
|
"[STATUS] == 200"
|
|
]; # Health check conditions. Setting conditions enables health checks.
|
|
monitoring.healthCheck.enable = true; # No description
|
|
monitoring.healthCheck.extraChecks = []; # Additional health checks. Adding checks enables health monitoring.
|
|
# monitoring.healthCheck.path = <null or string>; # Health check endpoint path. Setting this enables health checks.
|
|
monitoring.metrics.enable = false; # No description
|
|
monitoring.metrics.extraEndpoints = []; # Additional metrics endpoints. Adding endpoints enables metrics collection.
|
|
# monitoring.metrics.path = <null or string>; # Metrics endpoint path. Setting this enables metrics collection.
|
|
};
|
|
```
|
|
|
|
**example sets these monitoring defaults:**
|
|
```nix
|
|
enable = true;
|
|
extraLabels = {};
|
|
healthCheck = {"conditions":["[STATUS] == 200"],"enable":true,"extraChecks":[],"path":null};
|
|
metrics = {"enable":false,"extraEndpoints":[],"path":null};
|
|
```
|
|
|
|
##### 📝 Logging Integration
|
|
|
|
Available logging options:
|
|
|
|
```nix
|
|
homelab.services.example = {
|
|
# ... core options above ...
|
|
|
|
logging.enable = false; # Enable logging for example
|
|
logging.extraLabels = {}; # No description
|
|
logging.extraSources = []; # No description
|
|
logging.files = []; # No description
|
|
# logging.multiline = <null or (submodule)>; # No description
|
|
logging.parsing.extractFields = []; # No description
|
|
# logging.parsing.regex = <null or string>; # No description
|
|
};
|
|
```
|
|
|
|
**example sets these logging defaults:**
|
|
```nix
|
|
enable = false;
|
|
extraLabels = {};
|
|
extraSources = [];
|
|
files = [];
|
|
multiline = null;
|
|
parsing = {"extractFields":[],"regex":null};
|
|
```
|
|
|
|
##### 🔀 Proxy Integration
|
|
|
|
Available proxy options:
|
|
|
|
```nix
|
|
homelab.services.example = {
|
|
# ... core options above ...
|
|
|
|
proxy.additionalSubdomains = []; # No description
|
|
proxy.enable = true; # Enable reverse proxy for example
|
|
proxy.enableAuth = false; # No description
|
|
proxy.subdomain = example; # No description
|
|
};
|
|
```
|
|
|
|
**example sets these proxy defaults:**
|
|
```nix
|
|
additionalSubdomains = [];
|
|
enable = true;
|
|
enableAuth = false;
|
|
subdomain = example;
|
|
```
|
|
|
|
---
|
|
|
|
### gatus
|
|
|
|
**Deployment Status:** 1/2 nodes have this service enabled
|
|
|
|
#### Core Service Options
|
|
|
|
The main configuration options for gatus:
|
|
|
|
```nix
|
|
homelab.services.gatus = {
|
|
alerting = {}; # Gatus alerting configuration
|
|
description = Gatus Status Page; # No description
|
|
enable = false; # Whether to enable Gatus Status Page.
|
|
extraConfig = {}; # Additional Gatus configuration options
|
|
port = 8080; # No description
|
|
storage = {
|
|
"type": "memory"
|
|
}; # Gatus storage configuration
|
|
ui.buttons = [
|
|
{
|
|
"link": "https://grafana.procopius.dk",
|
|
"name": "Grafana"
|
|
},
|
|
{
|
|
"link": "https://prometheus.procopius.dk",
|
|
"name": "Prometheus"
|
|
}
|
|
]; # Navigation buttons in the Gatus interface
|
|
ui.header = Homelab Services Status; # Header text for the Gatus interface
|
|
ui.link = https://status.procopius.dk; # Link in the Gatus header
|
|
ui.title = Homelab Status; # Title for the Gatus web interface
|
|
web.address = 0.0.0.0; # Web interface bind address
|
|
};
|
|
```
|
|
|
|
#### Feature Integrations
|
|
|
|
##### 📊 Monitoring Integration
|
|
|
|
Available monitoring options:
|
|
|
|
```nix
|
|
homelab.services.gatus = {
|
|
# ... core options above ...
|
|
|
|
monitoring.enable = true; # Enable monitoring for gatus
|
|
monitoring.extraLabels = {}; # No description
|
|
monitoring.healthCheck.conditions = [
|
|
"[STATUS] == 200"
|
|
]; # Health check conditions. Setting conditions enables health checks.
|
|
monitoring.healthCheck.enable = true; # No description
|
|
monitoring.healthCheck.extraChecks = []; # Additional health checks. Adding checks enables health monitoring.
|
|
# monitoring.healthCheck.path = <null or string>; # Health check endpoint path. Setting this enables health checks.
|
|
monitoring.metrics.enable = false; # No description
|
|
monitoring.metrics.extraEndpoints = []; # Additional metrics endpoints. Adding endpoints enables metrics collection.
|
|
# monitoring.metrics.path = <null or string>; # Metrics endpoint path. Setting this enables metrics collection.
|
|
};
|
|
```
|
|
|
|
**gatus sets these monitoring defaults:**
|
|
```nix
|
|
enable = true;
|
|
extraLabels = {};
|
|
healthCheck = {"conditions":["[STATUS] == 200"],"enable":true,"extraChecks":[],"path":null};
|
|
metrics = {"enable":false,"extraEndpoints":[],"path":null};
|
|
```
|
|
|
|
##### 📝 Logging Integration
|
|
|
|
Available logging options:
|
|
|
|
```nix
|
|
homelab.services.gatus = {
|
|
# ... core options above ...
|
|
|
|
logging.enable = false; # Enable logging for gatus
|
|
logging.extraLabels = {}; # No description
|
|
logging.extraSources = []; # No description
|
|
logging.files = []; # No description
|
|
# logging.multiline = <null or (submodule)>; # No description
|
|
logging.parsing.extractFields = []; # No description
|
|
# logging.parsing.regex = <null or string>; # No description
|
|
};
|
|
```
|
|
|
|
**gatus sets these logging defaults:**
|
|
```nix
|
|
enable = false;
|
|
extraLabels = {};
|
|
extraSources = [];
|
|
files = [];
|
|
multiline = null;
|
|
parsing = {"extractFields":[],"regex":null};
|
|
```
|
|
|
|
##### 🔀 Proxy Integration
|
|
|
|
Available proxy options:
|
|
|
|
```nix
|
|
homelab.services.gatus = {
|
|
# ... core options above ...
|
|
|
|
proxy.additionalSubdomains = []; # No description
|
|
proxy.enable = true; # Enable reverse proxy for gatus
|
|
proxy.enableAuth = false; # No description
|
|
proxy.subdomain = gatus; # No description
|
|
};
|
|
```
|
|
|
|
**gatus sets these proxy defaults:**
|
|
```nix
|
|
additionalSubdomains = [];
|
|
enable = true;
|
|
enableAuth = false;
|
|
subdomain = gatus;
|
|
```
|
|
|
|
---
|
|
|
|
### grafana
|
|
|
|
**Deployment Status:** 1/2 nodes have this service enabled
|
|
|
|
#### Core Service Options
|
|
|
|
The main configuration options for grafana:
|
|
|
|
```nix
|
|
homelab.services.grafana = {
|
|
description = Grafana Metrics Dashboard; # No description
|
|
enable = false; # Whether to enable Grafana Dashboard.
|
|
port = 3000; # No description
|
|
};
|
|
```
|
|
|
|
#### Feature Integrations
|
|
|
|
##### 📊 Monitoring Integration
|
|
|
|
Available monitoring options:
|
|
|
|
```nix
|
|
homelab.services.grafana = {
|
|
# ... core options above ...
|
|
|
|
monitoring.enable = true; # Enable monitoring for grafana
|
|
monitoring.extraLabels = {}; # No description
|
|
monitoring.healthCheck.conditions = [
|
|
"[STATUS] == 200"
|
|
]; # Health check conditions. Setting conditions enables health checks.
|
|
monitoring.healthCheck.enable = true; # No description
|
|
monitoring.healthCheck.extraChecks = []; # Additional health checks. Adding checks enables health monitoring.
|
|
# monitoring.healthCheck.path = <null or string>; # Health check endpoint path. Setting this enables health checks.
|
|
monitoring.metrics.enable = false; # No description
|
|
monitoring.metrics.extraEndpoints = []; # Additional metrics endpoints. Adding endpoints enables metrics collection.
|
|
# monitoring.metrics.path = <null or string>; # Metrics endpoint path. Setting this enables metrics collection.
|
|
};
|
|
```
|
|
|
|
**grafana sets these monitoring defaults:**
|
|
```nix
|
|
enable = true;
|
|
extraLabels = {};
|
|
healthCheck = {"conditions":["[STATUS] == 200"],"enable":true,"extraChecks":[],"path":null};
|
|
metrics = {"enable":false,"extraEndpoints":[],"path":null};
|
|
```
|
|
|
|
##### 📝 Logging Integration
|
|
|
|
Available logging options:
|
|
|
|
```nix
|
|
homelab.services.grafana = {
|
|
# ... core options above ...
|
|
|
|
logging.enable = false; # Enable logging for grafana
|
|
logging.extraLabels = {}; # No description
|
|
logging.extraSources = []; # No description
|
|
logging.files = []; # No description
|
|
# logging.multiline = <null or (submodule)>; # No description
|
|
logging.parsing.extractFields = []; # No description
|
|
# logging.parsing.regex = <null or string>; # No description
|
|
};
|
|
```
|
|
|
|
**grafana sets these logging defaults:**
|
|
```nix
|
|
enable = false;
|
|
extraLabels = {};
|
|
extraSources = [];
|
|
files = [];
|
|
multiline = null;
|
|
parsing = {"extractFields":[],"regex":null};
|
|
```
|
|
|
|
##### 🔀 Proxy Integration
|
|
|
|
Available proxy options:
|
|
|
|
```nix
|
|
homelab.services.grafana = {
|
|
# ... core options above ...
|
|
|
|
proxy.additionalSubdomains = []; # No description
|
|
proxy.enable = true; # Enable reverse proxy for grafana
|
|
proxy.enableAuth = false; # No description
|
|
proxy.subdomain = grafana; # No description
|
|
};
|
|
```
|
|
|
|
**grafana sets these proxy defaults:**
|
|
```nix
|
|
additionalSubdomains = [];
|
|
enable = true;
|
|
enableAuth = false;
|
|
subdomain = grafana;
|
|
```
|
|
|
|
---
|
|
|
|
### minio
|
|
|
|
**Deployment Status:** 1/2 nodes have this service enabled
|
|
|
|
#### Core Service Options
|
|
|
|
The main configuration options for minio:
|
|
|
|
```nix
|
|
homelab.services.minio = {
|
|
enable = false; # Whether to enable Minio Object Storage.
|
|
openFirewall = true; # Whether to open the ports specified in `port` and `webPort` in the firewall.
|
|
port = 9000; # Port of the server.
|
|
webPort = 9001; # Port of the web UI (console).
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
### prometheus
|
|
|
|
**Deployment Status:** 1/2 nodes have this service enabled
|
|
|
|
#### Core Service Options
|
|
|
|
The main configuration options for prometheus:
|
|
|
|
```nix
|
|
homelab.services.prometheus = {
|
|
alertmanager.enable = true; # Enable integration with Alertmanager
|
|
alertmanager.url = alertmanager.lab:9093; # Alertmanager URL
|
|
description = Prometheus Monitoring Server; # No description
|
|
enable = false; # Whether to enable Prometheus Monitoring Server.
|
|
extraAlertingRules = []; # Additional alerting rules
|
|
extraFlags = []; # Extra command line flags
|
|
extraScrapeConfigs = []; # Additional scrape configurations
|
|
globalConfig = {
|
|
"evaluation_interval": "15s",
|
|
"scrape_interval": "15s"
|
|
}; # Global Prometheus configuration
|
|
port = 9090; # No description
|
|
retention = 15d; # How long to retain metrics data
|
|
ruleFiles = []; # Additional rule files to load
|
|
systemdServices = [
|
|
"prometheus.service",
|
|
"prometheus"
|
|
]; # Systemd services to monitor
|
|
};
|
|
```
|
|
|
|
#### Feature Integrations
|
|
|
|
##### 📊 Monitoring Integration
|
|
|
|
Available monitoring options:
|
|
|
|
```nix
|
|
homelab.services.prometheus = {
|
|
# ... core options above ...
|
|
|
|
monitoring.enable = true; # Enable monitoring for prometheus
|
|
monitoring.extraLabels = {}; # No description
|
|
monitoring.healthCheck.conditions = [
|
|
"[STATUS] == 200"
|
|
]; # Health check conditions. Setting conditions enables health checks.
|
|
monitoring.healthCheck.enable = true; # No description
|
|
monitoring.healthCheck.extraChecks = []; # Additional health checks. Adding checks enables health monitoring.
|
|
# monitoring.healthCheck.path = <null or string>; # Health check endpoint path. Setting this enables health checks.
|
|
monitoring.metrics.enable = false; # No description
|
|
monitoring.metrics.extraEndpoints = []; # Additional metrics endpoints. Adding endpoints enables metrics collection.
|
|
# monitoring.metrics.path = <null or string>; # Metrics endpoint path. Setting this enables metrics collection.
|
|
};
|
|
```
|
|
|
|
**prometheus sets these monitoring defaults:**
|
|
```nix
|
|
enable = true;
|
|
extraLabels = {};
|
|
healthCheck = {"conditions":["[STATUS] == 200"],"enable":true,"extraChecks":[],"path":null};
|
|
metrics = {"enable":false,"extraEndpoints":[],"path":null};
|
|
```
|
|
|
|
##### 📝 Logging Integration
|
|
|
|
Available logging options:
|
|
|
|
```nix
|
|
homelab.services.prometheus = {
|
|
# ... core options above ...
|
|
|
|
logging.enable = false; # Enable logging for prometheus
|
|
logging.extraLabels = {}; # No description
|
|
logging.extraSources = []; # No description
|
|
logging.files = []; # No description
|
|
# logging.multiline = <null or (submodule)>; # No description
|
|
logging.parsing.extractFields = []; # No description
|
|
# logging.parsing.regex = <null or string>; # No description
|
|
};
|
|
```
|
|
|
|
**prometheus sets these logging defaults:**
|
|
```nix
|
|
enable = false;
|
|
extraLabels = {};
|
|
extraSources = [];
|
|
files = [];
|
|
multiline = null;
|
|
parsing = {"extractFields":[],"regex":null};
|
|
```
|
|
|
|
##### 🔀 Proxy Integration
|
|
|
|
Available proxy options:
|
|
|
|
```nix
|
|
homelab.services.prometheus = {
|
|
# ... core options above ...
|
|
|
|
proxy.additionalSubdomains = []; # No description
|
|
proxy.enable = true; # Enable reverse proxy for prometheus
|
|
proxy.enableAuth = false; # No description
|
|
proxy.subdomain = prometheus; # No description
|
|
};
|
|
```
|
|
|
|
**prometheus sets these proxy defaults:**
|
|
```nix
|
|
additionalSubdomains = [];
|
|
enable = true;
|
|
enableAuth = false;
|
|
subdomain = prometheus;
|
|
```
|
|
|
|
---
|
|
|
|
## Feature Reference
|
|
|
|
### Integration Features
|
|
|
|
Homelab services can integrate with three main features:
|
|
|
|
- **📊 Monitoring**: Prometheus metrics and health checks
|
|
- **📝 Logging**: Centralized log collection with Promtail/Loki
|
|
- **🔀 Proxy**: Reverse proxy with SSL and authentication
|
|
|
|
Each service can import these features and set service-specific defaults.
|
|
|
|
---
|
|
|
|
*This documentation is generated from actual NixOS module evaluations.*
|