929 lines
41 KiB
Python
929 lines
41 KiB
Python
#!/usr/bin/env python3
|
|
"""
|
|
Generate comprehensive documentation for all homelab services.
|
|
This script analyzes Docker Compose files and creates detailed documentation for each service.
|
|
"""
|
|
|
|
import os
|
|
import yaml
|
|
import re
|
|
from pathlib import Path
|
|
from typing import Dict, List, Any, Optional
|
|
|
|
class ServiceDocumentationGenerator:
|
|
def __init__(self, repo_path: str):
|
|
self.repo_path = Path(repo_path)
|
|
self.docs_path = self.repo_path / "docs" / "services" / "individual"
|
|
self.docs_path.mkdir(parents=True, exist_ok=True)
|
|
|
|
# Service categories for better organization
|
|
self.categories = {
|
|
'media': ['plex', 'jellyfin', 'emby', 'tautulli', 'overseerr', 'ombi', 'radarr', 'sonarr', 'lidarr', 'readarr', 'bazarr', 'prowlarr', 'jackett', 'nzbget', 'sabnzbd', 'transmission', 'qbittorrent', 'deluge', 'immich', 'photoprism', 'navidrome', 'airsonic', 'calibre', 'komga', 'kavita'],
|
|
'monitoring': ['grafana', 'prometheus', 'uptime-kuma', 'uptimerobot', 'statping', 'healthchecks', 'netdata', 'zabbix', 'nagios', 'icinga', 'librenms', 'observium', 'cacti', 'ntopng', 'bandwidthd', 'darkstat', 'vnstat', 'smokeping', 'blackbox-exporter', 'node-exporter', 'cadvisor', 'exportarr'],
|
|
'productivity': ['nextcloud', 'owncloud', 'seafile', 'syncthing', 'filebrowser', 'paperless-ngx', 'paperless', 'docspell', 'teedy', 'bookstack', 'dokuwiki', 'tiddlywiki', 'outline', 'siyuan', 'logseq', 'obsidian', 'joplin', 'standardnotes', 'trilium', 'zettlr', 'typora', 'marktext', 'ghostwriter', 'remarkable', 'xournalpp', 'rnote', 'firefly-iii', 'actual-budget', 'budget-zen', 'maybe-finance', 'kresus', 'homebank', 'gnucash', 'ledger', 'beancount', 'plaintextaccounting'],
|
|
'development': ['gitea', 'gitlab', 'github', 'bitbucket', 'sourcehut', 'forgejo', 'cgit', 'gitweb', 'jenkins', 'drone', 'woodpecker', 'buildkite', 'teamcity', 'bamboo', 'travis', 'circleci', 'github-actions', 'gitlab-ci', 'azure-devops', 'aws-codebuild', 'portainer', 'yacht', 'dockge', 'lazydocker', 'ctop', 'dive', 'docker-compose-ui', 'docker-registry', 'harbor', 'quay', 'nexus', 'artifactory', 'verdaccio', 'npm-registry'],
|
|
'communication': ['matrix-synapse', 'element', 'riot', 'nheko', 'fluffychat', 'cinny', 'hydrogen', 'schildichat', 'mattermost', 'rocket-chat', 'zulip', 'slack', 'discord', 'telegram', 'signal', 'whatsapp', 'messenger', 'skype', 'zoom', 'jitsi', 'bigbluebutton', 'jami', 'briar', 'session', 'wickr', 'threema', 'wire', 'keybase', 'mastodon', 'pleroma', 'misskey', 'diaspora', 'friendica', 'hubzilla', 'peertube', 'pixelfed', 'lemmy', 'kbin'],
|
|
'security': ['vaultwarden', 'bitwarden', 'keepass', 'passbolt', 'psono', 'teampass', 'pleasant-password', 'authelia', 'authentik', 'keycloak', 'gluu', 'freeipa', 'openldap', 'active-directory', 'okta', 'auth0', 'firebase-auth', 'aws-cognito', 'azure-ad', 'google-identity', 'pihole', 'adguard', 'blocky', 'unbound', 'bind9', 'powerdns', 'coredns', 'technitium', 'wireguard', 'openvpn', 'ipsec', 'tinc', 'zerotier', 'tailscale', 'nebula', 'headscale'],
|
|
'networking': ['nginx', 'apache', 'caddy', 'traefik', 'haproxy', 'envoy', 'istio', 'linkerd', 'consul', 'vault', 'nomad', 'pfsense', 'opnsense', 'vyos', 'mikrotik', 'ubiquiti', 'tp-link', 'netgear', 'asus', 'linksys', 'dlink', 'zyxel', 'fortinet', 'sonicwall', 'watchguard', 'palo-alto', 'checkpoint', 'juniper', 'cisco', 'arista', 'cumulus', 'sonic', 'frr', 'quagga', 'bird', 'openbgpd'],
|
|
'storage': ['minio', 's3', 'ceph', 'glusterfs', 'moosefs', 'lizardfs', 'orangefs', 'lustre', 'beegfs', 'gpfs', 'hdfs', 'cassandra', 'mongodb', 'postgresql', 'mysql', 'mariadb', 'sqlite', 'redis', 'memcached', 'elasticsearch', 'solr', 'sphinx', 'whoosh', 'xapian', 'lucene', 'influxdb', 'prometheus', 'graphite', 'opentsdb', 'kairosdb', 'druid', 'clickhouse', 'timescaledb'],
|
|
'gaming': ['minecraft', 'factorio', 'satisfactory', 'valheim', 'terraria', 'starbound', 'dont-starve', 'project-zomboid', 'rust', 'ark', 'conan-exiles', 'space-engineers', 'astroneer', 'raft', 'green-hell', 'the-forest', 'subnautica', 'no-mans-sky', 'elite-dangerous', 'star-citizen', 'eve-online', 'world-of-warcraft', 'final-fantasy-xiv', 'guild-wars-2', 'elder-scrolls-online', 'destiny-2', 'warframe', 'path-of-exile', 'diablo', 'torchlight', 'grim-dawn', 'last-epoch'],
|
|
'ai': ['ollama', 'llamagpt', 'chatgpt', 'gpt4all', 'localai', 'text-generation-webui', 'koboldai', 'novelai', 'stable-diffusion', 'automatic1111', 'invokeai', 'comfyui', 'fooocus', 'easydiffusion', 'diffusionbee', 'draw-things', 'whisper', 'faster-whisper', 'vosk', 'deepspeech', 'wav2vec', 'espnet', 'kaldi', 'julius', 'pocketsphinx', 'festival', 'espeak', 'mary-tts', 'mimic', 'tacotron', 'wavenet', 'neural-voices']
|
|
}
|
|
|
|
def find_compose_files(self) -> List[Path]:
|
|
"""Find all YAML files that contain Docker Compose configurations."""
|
|
compose_files = []
|
|
|
|
# Find all YAML files
|
|
yaml_files = list(self.repo_path.rglob('*.yml')) + list(self.repo_path.rglob('*.yaml'))
|
|
|
|
# Filter out files in docs, .git, and other non-service directories
|
|
filtered_files = []
|
|
for file in yaml_files:
|
|
path_parts = file.parts
|
|
if any(part in path_parts for part in ['.git', 'docs', 'node_modules', '.vscode', '__pycache__', 'ansible']):
|
|
continue
|
|
|
|
# Check if file contains Docker Compose configuration
|
|
try:
|
|
with open(file, 'r', encoding='utf-8') as f:
|
|
content = f.read()
|
|
# Look for Docker Compose indicators
|
|
if ('services:' in content and
|
|
('version:' in content or 'image:' in content or 'build:' in content)):
|
|
filtered_files.append(file)
|
|
except Exception as e:
|
|
print(f"Warning: Could not read {file}: {e}")
|
|
continue
|
|
|
|
return sorted(filtered_files)
|
|
|
|
def parse_compose_file(self, compose_file: Path) -> Dict[str, Any]:
|
|
"""Parse a docker-compose file and extract service information."""
|
|
try:
|
|
with open(compose_file, 'r', encoding='utf-8') as f:
|
|
content = yaml.safe_load(f)
|
|
|
|
if not content or 'services' not in content:
|
|
return {}
|
|
|
|
# Extract metadata from file path
|
|
relative_path = compose_file.relative_to(self.repo_path)
|
|
host = relative_path.parts[0] if len(relative_path.parts) > 1 else 'unknown'
|
|
|
|
services_info = {}
|
|
for service_name, service_config in content['services'].items():
|
|
services_info[service_name] = {
|
|
'config': service_config,
|
|
'host': host,
|
|
'compose_file': str(relative_path),
|
|
'directory': str(compose_file.parent.relative_to(self.repo_path))
|
|
}
|
|
|
|
return services_info
|
|
|
|
except Exception as e:
|
|
print(f"Error parsing {compose_file}: {e}")
|
|
return {}
|
|
|
|
def categorize_service(self, service_name: str, image: str = '') -> str:
|
|
"""Categorize a service based on its name and image."""
|
|
service_lower = service_name.lower().replace('-', '').replace('_', '')
|
|
image_lower = image.lower() if image else ''
|
|
|
|
for category, keywords in self.categories.items():
|
|
for keyword in keywords:
|
|
keyword_clean = keyword.replace('-', '').replace('_', '')
|
|
if keyword_clean in service_lower or keyword_clean in image_lower:
|
|
return category
|
|
|
|
return 'other'
|
|
|
|
def extract_ports(self, service_config: Dict) -> List[str]:
|
|
"""Extract port mappings from service configuration."""
|
|
ports = []
|
|
if 'ports' in service_config:
|
|
for port in service_config['ports']:
|
|
if isinstance(port, str):
|
|
ports.append(port)
|
|
elif isinstance(port, dict):
|
|
target = port.get('target', '')
|
|
published = port.get('published', '')
|
|
if target and published:
|
|
ports.append(f"{published}:{target}")
|
|
return ports
|
|
|
|
def extract_volumes(self, service_config: Dict) -> List[str]:
|
|
"""Extract volume mappings from service configuration."""
|
|
volumes = []
|
|
if 'volumes' in service_config:
|
|
for volume in service_config['volumes']:
|
|
if isinstance(volume, str):
|
|
volumes.append(volume)
|
|
elif isinstance(volume, dict):
|
|
source = volume.get('source', '')
|
|
target = volume.get('target', '')
|
|
if source and target:
|
|
volumes.append(f"{source}:{target}")
|
|
return volumes
|
|
|
|
def extract_environment(self, service_config: Dict) -> Dict[str, str]:
|
|
"""Extract environment variables from service configuration."""
|
|
env_vars = {}
|
|
if 'environment' in service_config:
|
|
env = service_config['environment']
|
|
if isinstance(env, list):
|
|
for var in env:
|
|
if '=' in var:
|
|
key, value = var.split('=', 1)
|
|
env_vars[key] = value
|
|
elif isinstance(env, dict):
|
|
env_vars = env
|
|
return env_vars
|
|
|
|
def get_difficulty_level(self, service_name: str, service_config: Dict) -> str:
|
|
"""Determine difficulty level based on service complexity."""
|
|
# Advanced services (require significant expertise)
|
|
advanced_keywords = [
|
|
'gitlab', 'jenkins', 'kubernetes', 'consul', 'vault', 'nomad',
|
|
'elasticsearch', 'cassandra', 'mongodb-cluster', 'postgresql-cluster',
|
|
'matrix-synapse', 'mastodon', 'peertube', 'nextcloud', 'keycloak',
|
|
'authentik', 'authelia', 'traefik', 'istio', 'linkerd'
|
|
]
|
|
|
|
# Intermediate services (require basic Docker/Linux knowledge)
|
|
intermediate_keywords = [
|
|
'grafana', 'prometheus', 'nginx', 'caddy', 'haproxy', 'wireguard',
|
|
'openvpn', 'pihole', 'adguard', 'vaultwarden', 'bitwarden',
|
|
'paperless', 'bookstack', 'dokuwiki', 'mattermost', 'rocket-chat',
|
|
'portainer', 'yacht', 'immich', 'photoprism', 'jellyfin', 'emby'
|
|
]
|
|
|
|
service_lower = service_name.lower()
|
|
image = service_config.get('image', '').lower()
|
|
|
|
# Check for advanced complexity indicators
|
|
has_depends_on = 'depends_on' in service_config
|
|
has_multiple_volumes = len(service_config.get('volumes', [])) > 3
|
|
has_complex_networking = 'networks' in service_config and len(service_config['networks']) > 1
|
|
has_build_config = 'build' in service_config
|
|
|
|
if any(keyword in service_lower or keyword in image for keyword in advanced_keywords):
|
|
return '🔴'
|
|
elif (any(keyword in service_lower or keyword in image for keyword in intermediate_keywords) or
|
|
has_depends_on or has_multiple_volumes or has_complex_networking or has_build_config):
|
|
return '🟡'
|
|
else:
|
|
return '🟢'
|
|
|
|
def generate_service_documentation(self, service_name: str, service_info: Dict) -> str:
|
|
"""Generate comprehensive documentation for a single service."""
|
|
config = service_info['config']
|
|
host = service_info['host']
|
|
compose_file = service_info['compose_file']
|
|
directory = service_info['directory']
|
|
|
|
# Extract key information
|
|
image = config.get('image', 'Unknown')
|
|
ports = self.extract_ports(config)
|
|
volumes = self.extract_volumes(config)
|
|
env_vars = self.extract_environment(config)
|
|
category = self.categorize_service(service_name, image)
|
|
difficulty = self.get_difficulty_level(service_name, config)
|
|
|
|
# Generate documentation content
|
|
doc_content = f"""# {service_name.title().replace('-', ' ').replace('_', ' ')}
|
|
|
|
**{difficulty} {category.title()} Service**
|
|
|
|
## 📋 Service Overview
|
|
|
|
| Property | Value |
|
|
|----------|-------|
|
|
| **Service Name** | {service_name} |
|
|
| **Host** | {host} |
|
|
| **Category** | {category.title()} |
|
|
| **Difficulty** | {difficulty} |
|
|
| **Docker Image** | `{image}` |
|
|
| **Compose File** | `{compose_file}` |
|
|
| **Directory** | `{directory}` |
|
|
|
|
## 🎯 Purpose
|
|
|
|
{self.get_service_description(service_name, image, category)}
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
- Docker and Docker Compose installed
|
|
- Basic understanding of REDACTED_APP_PASSWORD
|
|
- Access to the host system ({host})
|
|
|
|
### Deployment
|
|
```bash
|
|
# Navigate to service directory
|
|
cd {directory}
|
|
|
|
# Start the service
|
|
docker-compose up -d
|
|
|
|
# Check service status
|
|
docker-compose ps
|
|
|
|
# View logs
|
|
docker-compose logs -f {service_name}
|
|
```
|
|
|
|
## 🔧 Configuration
|
|
|
|
### Docker Compose Configuration
|
|
```yaml
|
|
{self.format_compose_config(config)}
|
|
```
|
|
|
|
### Environment Variables
|
|
{self.format_environment_variables(env_vars)}
|
|
|
|
### Port Mappings
|
|
{self.format_ports(ports)}
|
|
|
|
### Volume Mappings
|
|
{self.format_volumes(volumes)}
|
|
|
|
## 🌐 Access Information
|
|
|
|
{self.generate_access_info(service_name, ports, host)}
|
|
|
|
## 🔒 Security Considerations
|
|
|
|
{self.generate_security_info(service_name, config)}
|
|
|
|
## 📊 Resource Requirements
|
|
|
|
{self.generate_resource_info(config)}
|
|
|
|
## 🔍 Health Monitoring
|
|
|
|
{self.generate_health_info(config)}
|
|
|
|
## 🚨 Troubleshooting
|
|
|
|
### Common Issues
|
|
{self.generate_troubleshooting_info(service_name, category)}
|
|
|
|
### Useful Commands
|
|
```bash
|
|
# Check service status
|
|
docker-compose ps
|
|
|
|
# View real-time logs
|
|
docker-compose logs -f {service_name}
|
|
|
|
# Restart service
|
|
docker-compose restart {service_name}
|
|
|
|
# Update service
|
|
docker-compose pull {service_name}
|
|
docker-compose up -d {service_name}
|
|
|
|
# Access service shell
|
|
docker-compose exec {service_name} /bin/bash
|
|
# or
|
|
docker-compose exec {service_name} /bin/sh
|
|
```
|
|
|
|
## 📚 Additional Resources
|
|
|
|
{self.generate_additional_resources(service_name, image)}
|
|
|
|
## 🔗 Related Services
|
|
|
|
{self.generate_related_services(service_name, category, host)}
|
|
|
|
---
|
|
|
|
*This documentation is auto-generated from the Docker Compose configuration. For the most up-to-date information, refer to the official documentation and the actual compose file.*
|
|
|
|
**Last Updated**: {self.get_current_date()}
|
|
**Configuration Source**: `{compose_file}`
|
|
"""
|
|
return doc_content
|
|
|
|
def get_service_description(self, service_name: str, image: str, category: str) -> str:
|
|
"""Generate a description for the service based on its name and category."""
|
|
descriptions = {
|
|
'plex': 'Plex Media Server organizes video, music and photos from personal media libraries and streams them to smart TVs, streaming boxes and mobile devices.',
|
|
'jellyfin': 'Jellyfin is a Free Software Media System that puts you in control of managing and streaming your media.',
|
|
'grafana': 'Grafana is the open source analytics & monitoring solution for every database.',
|
|
'prometheus': 'Prometheus is an open-source systems monitoring and alerting toolkit.',
|
|
'uptime-kuma': 'Uptime Kuma is a fancy self-hosted monitoring tool.',
|
|
'nginx': 'NGINX is a web server that can also be used as a reverse proxy, load balancer, mail proxy and HTTP cache.',
|
|
'traefik': 'Traefik is a modern HTTP reverse proxy and load balancer that makes deploying microservices easy.',
|
|
'portainer': 'Portainer is a lightweight management UI which allows you to easily manage your different Docker environments.',
|
|
'vaultwarden': 'Vaultwarden is an alternative implementation of the Bitwarden server API written in Rust and compatible with upstream Bitwarden clients.',
|
|
'pihole': 'Pi-hole is a DNS sinkhole that protects your devices from unwanted content, without installing any client-side software.',
|
|
'adguard': 'AdGuard Home is a network-wide software for blocking ads & tracking.',
|
|
'wireguard': 'WireGuard is an extremely simple yet fast and modern VPN that utilizes state-of-the-art cryptography.',
|
|
'nextcloud': 'Nextcloud is a suite of client-server software for creating and using file hosting services.',
|
|
'immich': 'High performance self-hosted photo and video backup solution.',
|
|
'paperless-ngx': 'Paperless-ngx is a document management system that transforms your physical documents into a searchable online archive.',
|
|
'gitea': 'Gitea is a community managed lightweight code hosting solution written in Go.',
|
|
'gitlab': 'GitLab is a web-based DevOps lifecycle tool that provides a Git-repository manager.',
|
|
'mattermost': 'Mattermost is an open-source, self-hostable online chat service with file sharing, search, and integrations.',
|
|
'matrix-synapse': 'Matrix Synapse is a reference homeserver implementation of the Matrix protocol.',
|
|
'mastodon': 'Mastodon is a free and open-source self-hosted social networking service.',
|
|
'minecraft': 'Minecraft server for multiplayer gaming.',
|
|
'factorio': 'Factorio dedicated server for multiplayer factory building.',
|
|
'satisfactory': 'Satisfactory dedicated server for multiplayer factory building in 3D.',
|
|
'ollama': 'Ollama is a tool for running large language models locally.',
|
|
'whisper': 'OpenAI Whisper is an automatic speech recognition system.',
|
|
'stable-diffusion': 'Stable Diffusion is a deep learning, text-to-image model.',
|
|
}
|
|
|
|
service_key = service_name.lower().replace('-', '').replace('_', '')
|
|
|
|
# Try exact match first
|
|
if service_key in descriptions:
|
|
return descriptions[service_key]
|
|
|
|
# Try partial matches
|
|
for key, desc in descriptions.items():
|
|
if key in service_key or service_key in key:
|
|
return desc
|
|
|
|
# Generate generic description based on category
|
|
category_descriptions = {
|
|
'media': f'{service_name} is a media management and streaming service that helps organize and serve your digital media content.',
|
|
'monitoring': f'{service_name} is a monitoring and observability tool that helps track system performance and health.',
|
|
'productivity': f'{service_name} is a productivity application that helps manage tasks, documents, or workflows.',
|
|
'development': f'{service_name} is a development tool that assists with code management, CI/CD, or software development workflows.',
|
|
'communication': f'{service_name} is a communication platform that enables messaging, collaboration, or social interaction.',
|
|
'security': f'{service_name} is a security tool that helps protect systems, manage authentication, or secure communications.',
|
|
'networking': f'{service_name} is a networking service that manages network traffic, routing, or connectivity.',
|
|
'storage': f'{service_name} is a storage solution that manages data persistence, backup, or file sharing.',
|
|
'gaming': f'{service_name} is a gaming server that hosts multiplayer games or gaming-related services.',
|
|
'ai': f'{service_name} is an AI/ML service that provides artificial intelligence or machine learning capabilities.',
|
|
'other': f'{service_name} is a specialized service that provides specific functionality for the homelab infrastructure.'
|
|
}
|
|
|
|
return category_descriptions.get(category, category_descriptions['other'])
|
|
|
|
def format_compose_config(self, config: Dict) -> str:
|
|
"""Format the Docker Compose configuration for display."""
|
|
try:
|
|
import yaml
|
|
return yaml.dump(config, default_flow_style=False, indent=2)
|
|
except:
|
|
return str(config)
|
|
|
|
def format_environment_variables(self, env_vars: Dict[str, str]) -> str:
|
|
"""Format environment variables for display."""
|
|
if not env_vars:
|
|
return "No environment variables configured."
|
|
|
|
result = "| Variable | Value | Description |\n|----------|-------|-------------|\n"
|
|
for key, value in env_vars.items():
|
|
# Mask sensitive values
|
|
display_value = value
|
|
if any(sensitive in key.lower() for sensitive in ['password', 'secret', 'key', 'token']):
|
|
display_value = '***MASKED***'
|
|
result += f"| `{key}` | `{display_value}` | {self.get_env_var_description(key)} |\n"
|
|
|
|
return result
|
|
|
|
def get_env_var_description(self, var_name: str) -> str:
|
|
"""Get description for common environment variables."""
|
|
descriptions = {
|
|
'TZ': 'Timezone setting',
|
|
'PUID': 'User ID for file permissions',
|
|
'PGID': 'Group ID for file permissions',
|
|
'MYSQL_ROOT_PASSWORD': 'MySQL root password',
|
|
'POSTGRES_PASSWORD': 'PostgreSQL password',
|
|
'REDIS_PASSWORD': 'Redis authentication password',
|
|
'ADMIN_PASSWORD': 'Administrator password',
|
|
'SECRET_KEY': 'Application secret key',
|
|
'JWT_SECRET': 'JWT signing secret',
|
|
'DATABASE_URL': 'Database connection string',
|
|
'DOMAIN': 'Service domain name',
|
|
'BASE_URL': 'Base URL for the service',
|
|
'DEBUG': 'Enable debug mode',
|
|
'LOG_LEVEL': 'Logging verbosity level'
|
|
}
|
|
|
|
var_lower = var_name.lower()
|
|
for key, desc in descriptions.items():
|
|
if key.lower() in var_lower:
|
|
return desc
|
|
|
|
return 'Configuration variable'
|
|
|
|
def format_ports(self, ports: List[str]) -> str:
|
|
"""Format port mappings for display."""
|
|
if not ports:
|
|
return "No ports exposed."
|
|
|
|
result = "| Host Port | Container Port | Protocol | Purpose |\n|-----------|----------------|----------|----------|\n"
|
|
for port in ports:
|
|
if ':' in port:
|
|
host_port, container_port = port.split(':', 1)
|
|
protocol = 'TCP'
|
|
if '/' in container_port:
|
|
container_port, protocol = container_port.split('/')
|
|
purpose = self.get_port_purpose(container_port)
|
|
result += f"| {host_port} | {container_port} | {protocol.upper()} | {purpose} |\n"
|
|
else:
|
|
result += f"| {port} | {port} | TCP | Service port |\n"
|
|
|
|
return result
|
|
|
|
def get_port_purpose(self, port: str) -> str:
|
|
"""Get the purpose of common ports."""
|
|
port_purposes = {
|
|
'80': 'HTTP web interface',
|
|
'443': 'HTTPS web interface',
|
|
'8080': 'Alternative HTTP port',
|
|
'8443': 'Alternative HTTPS port',
|
|
'3000': 'Web interface',
|
|
'9000': 'Management interface',
|
|
'5432': 'PostgreSQL database',
|
|
'3306': 'MySQL/MariaDB database',
|
|
'6379': 'Redis cache',
|
|
'27017': 'MongoDB database',
|
|
'9090': 'Prometheus metrics',
|
|
'3001': 'Monitoring interface',
|
|
'8086': 'InfluxDB',
|
|
'25565': 'Minecraft server',
|
|
'7777': 'Game server',
|
|
'22': 'SSH access',
|
|
'21': 'FTP',
|
|
'53': 'DNS',
|
|
'67': 'DHCP',
|
|
'123': 'NTP',
|
|
'161': 'SNMP',
|
|
'514': 'Syslog',
|
|
'1883': 'MQTT',
|
|
'8883': 'MQTT over SSL'
|
|
}
|
|
|
|
return port_purposes.get(port, 'Service port')
|
|
|
|
def format_volumes(self, volumes: List[str]) -> str:
|
|
"""Format volume mappings for display."""
|
|
if not volumes:
|
|
return "No volumes mounted."
|
|
|
|
result = "| Host Path | Container Path | Type | Purpose |\n|-----------|----------------|------|----------|\n"
|
|
for volume in volumes:
|
|
if ':' in volume:
|
|
parts = volume.split(':')
|
|
host_path = parts[0]
|
|
container_path = parts[1]
|
|
volume_type = 'bind' if host_path.startswith('/') or host_path.startswith('./') else 'volume'
|
|
purpose = self.get_volume_purpose(container_path)
|
|
result += f"| `{host_path}` | `{container_path}` | {volume_type} | {purpose} |\n"
|
|
else:
|
|
result += f"| `{volume}` | `{volume}` | volume | Data storage |\n"
|
|
|
|
return result
|
|
|
|
def get_volume_purpose(self, path: str) -> str:
|
|
"""Get the purpose of common volume paths."""
|
|
path_purposes = {
|
|
'/config': 'Configuration files',
|
|
'/data': 'Application data',
|
|
'/app/data': 'Application data',
|
|
'/var/lib': 'Service data',
|
|
'/etc': 'Configuration files',
|
|
'/logs': 'Log files',
|
|
'/var/log': 'System logs',
|
|
'/media': 'Media files',
|
|
'/downloads': 'Downloaded files',
|
|
'/uploads': 'Uploaded files',
|
|
'/backup': 'Backup files',
|
|
'/tmp': 'Temporary files',
|
|
'/cache': 'Cache data',
|
|
'/db': 'Database files',
|
|
'/ssl': 'SSL certificates',
|
|
'/keys': 'Encryption keys'
|
|
}
|
|
|
|
path_lower = path.lower()
|
|
for key, purpose in path_purposes.items():
|
|
if key in path_lower:
|
|
return purpose
|
|
|
|
return 'Data storage'
|
|
|
|
def generate_access_info(self, service_name: str, ports: List[str], host: str) -> str:
|
|
"""Generate access information for the service."""
|
|
if not ports:
|
|
return "This service does not expose any web interfaces."
|
|
|
|
web_ports = []
|
|
for port in ports:
|
|
if ':' in port:
|
|
host_port = port.split(':')[0]
|
|
container_port = port.split(':')[1].split('/')[0]
|
|
if container_port in ['80', '443', '8080', '8443', '3000', '9000', '8000', '5000']:
|
|
web_ports.append(host_port)
|
|
|
|
if not web_ports:
|
|
return f"Service ports: {', '.join(ports)}"
|
|
|
|
result = "### Web Interface\n"
|
|
for port in web_ports:
|
|
protocol = 'https' if port in ['443', '8443'] else 'http'
|
|
result += f"- **{protocol.upper()}**: `{protocol}://{host}:{port}`\n"
|
|
|
|
result += "\n### Default Credentials\n"
|
|
result += self.get_default_credentials(service_name)
|
|
|
|
return result
|
|
|
|
def get_default_credentials(self, service_name: str) -> str:
|
|
"""Get default credentials for common services."""
|
|
credentials = {
|
|
'grafana': 'Username: `admin`, Password: "REDACTED_PASSWORD" (change on first login)',
|
|
'portainer': 'Set admin password on first access',
|
|
'jenkins': 'Check logs for initial admin password',
|
|
'gitlab': 'Username: `root`, Password: "REDACTED_PASSWORD" `/etc/gitlab/initial_root_password`',
|
|
'nextcloud': 'Set admin credentials during initial setup',
|
|
'mattermost': 'Create admin account during setup',
|
|
'mastodon': 'Create admin account via command line',
|
|
'matrix-synapse': 'Create users via command line or admin API',
|
|
'uptime-kuma': 'Set admin credentials on first access',
|
|
'vaultwarden': 'Create account on first access',
|
|
'paperless-ngx': 'Create superuser via management command'
|
|
}
|
|
|
|
service_key = service_name.lower().replace('-', '').replace('_', '')
|
|
for key, creds in credentials.items():
|
|
if key in service_key or service_key in key:
|
|
return creds
|
|
|
|
return 'Refer to service documentation for default credentials'
|
|
|
|
def generate_security_info(self, service_name: str, config: Dict) -> str:
|
|
"""Generate security information for the service."""
|
|
security_info = []
|
|
|
|
# Check for security options
|
|
if 'security_opt' in config:
|
|
security_info.append("✅ Security options configured")
|
|
else:
|
|
security_info.append("⚠️ Consider adding security options (no-new-privileges)")
|
|
|
|
# Check for user mapping
|
|
if 'user' in config:
|
|
security_info.append("✅ Non-root user configured")
|
|
else:
|
|
security_info.append("⚠️ Consider running as non-root user")
|
|
|
|
# Check for read-only root filesystem
|
|
if config.get('read_only', False):
|
|
security_info.append("✅ Read-only root filesystem")
|
|
|
|
# Check for capabilities
|
|
if 'cap_drop' in config:
|
|
security_info.append("✅ Capabilities dropped")
|
|
|
|
# Add service-specific security recommendations
|
|
service_security = self.get_service_security_recommendations(service_name)
|
|
if service_security:
|
|
security_info.extend(service_security)
|
|
|
|
return '\n'.join(f"- {info}" for info in security_info)
|
|
|
|
def get_service_security_recommendations(self, service_name: str) -> List[str]:
|
|
"""Get security recommendations for specific services."""
|
|
recommendations = {
|
|
'vaultwarden': [
|
|
'🔒 Enable HTTPS with reverse proxy',
|
|
'🔒 Disable user registration after setup',
|
|
'🔒 Enable 2FA for all accounts',
|
|
'🔒 Regular database backups'
|
|
],
|
|
'nextcloud': [
|
|
'🔒 Enable HTTPS',
|
|
'🔒 Configure trusted domains',
|
|
'🔒 Enable 2FA',
|
|
'🔒 Regular security updates'
|
|
],
|
|
'gitlab': [
|
|
'🔒 Enable HTTPS',
|
|
'🔒 Configure SSH keys',
|
|
'🔒 Enable 2FA',
|
|
'🔒 Regular backups'
|
|
],
|
|
'matrix-synapse': [
|
|
'🔒 Enable HTTPS',
|
|
'🔒 Configure federation carefully',
|
|
'🔒 Regular database backups',
|
|
'🔒 Monitor resource usage'
|
|
]
|
|
}
|
|
|
|
service_key = service_name.lower().replace('-', '').replace('_', '')
|
|
for key, recs in recommendations.items():
|
|
if key in service_key or service_key in key:
|
|
return recs
|
|
|
|
return []
|
|
|
|
def generate_resource_info(self, config: Dict) -> str:
|
|
"""Generate resource requirement information."""
|
|
resource_info = []
|
|
|
|
# Check for resource limits
|
|
deploy_config = config.get('deploy', {})
|
|
resources = deploy_config.get('resources', {})
|
|
limits = resources.get('limits', {})
|
|
|
|
if limits:
|
|
if 'memory' in limits:
|
|
resource_info.append(f"**Memory Limit**: {limits['memory']}")
|
|
if 'cpus' in limits:
|
|
resource_info.append(f"**CPU Limit**: {limits['cpus']}")
|
|
else:
|
|
resource_info.append("No resource limits configured")
|
|
|
|
# Add general recommendations
|
|
resource_info.extend([
|
|
"",
|
|
"### Recommended Resources",
|
|
"- **Minimum RAM**: 512MB",
|
|
"- **Recommended RAM**: 1GB+",
|
|
"- **CPU**: 1 core minimum",
|
|
"- **Storage**: Varies by usage",
|
|
"",
|
|
"### Resource Monitoring",
|
|
"Monitor resource usage with:",
|
|
"```bash",
|
|
"docker stats",
|
|
"```"
|
|
])
|
|
|
|
return '\n'.join(resource_info)
|
|
|
|
def generate_health_info(self, config: Dict) -> str:
|
|
"""Generate health monitoring information."""
|
|
health_info = []
|
|
|
|
# Check for health check configuration
|
|
if 'healthcheck' in config:
|
|
health_config = config['healthcheck']
|
|
health_info.append("✅ Health check configured")
|
|
|
|
if 'test' in health_config:
|
|
test_cmd = health_config['test']
|
|
if isinstance(test_cmd, list):
|
|
test_cmd = ' '.join(test_cmd)
|
|
health_info.append(f"**Test Command**: `{test_cmd}`")
|
|
|
|
if 'interval' in health_config:
|
|
health_info.append(f"**Check Interval**: {health_config['interval']}")
|
|
|
|
if 'timeout' in health_config:
|
|
health_info.append(f"**Timeout**: {health_config['timeout']}")
|
|
|
|
if 'retries' in health_config:
|
|
health_info.append(f"**Retries**: {health_config['retries']}")
|
|
else:
|
|
health_info.append("⚠️ No health check configured")
|
|
health_info.append("Consider adding a health check:")
|
|
health_info.append("```yaml")
|
|
health_info.append("healthcheck:")
|
|
health_info.append(" test: [\"CMD\", \"curl\", \"-f\", \"http://localhost:PORT/health\"]")
|
|
health_info.append(" interval: 30s")
|
|
health_info.append(" timeout: 10s")
|
|
health_info.append(" retries: 3")
|
|
health_info.append("```")
|
|
|
|
# Add monitoring commands
|
|
health_info.extend([
|
|
"",
|
|
"### Manual Health Checks",
|
|
"```bash",
|
|
"# Check container health",
|
|
"docker inspect --format='{{.State.Health.Status}}' CONTAINER_NAME",
|
|
"",
|
|
"# View health check logs",
|
|
"docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' CONTAINER_NAME",
|
|
"```"
|
|
])
|
|
|
|
return '\n'.join(health_info)
|
|
|
|
def generate_troubleshooting_info(self, service_name: str, category: str) -> str:
|
|
"""Generate troubleshooting information."""
|
|
common_issues = [
|
|
"**Service won't start**",
|
|
"- Check Docker logs: `docker-compose logs service-name`",
|
|
"- Verify port availability: `netstat -tulpn | grep PORT`",
|
|
"- Check file permissions on mounted volumes",
|
|
"",
|
|
"**Can't access web interface**",
|
|
"- Verify service is running: `docker-compose ps`",
|
|
"- Check firewall settings",
|
|
"- Confirm correct port mapping",
|
|
"",
|
|
"**Performance issues**",
|
|
"- Monitor resource usage: `docker stats`",
|
|
"- Check available disk space: `df -h`",
|
|
"- Review service logs for errors"
|
|
]
|
|
|
|
# Add category-specific troubleshooting
|
|
category_issues = {
|
|
'media': [
|
|
"",
|
|
"**Media not showing**",
|
|
"- Check media file permissions",
|
|
"- Verify volume mounts are correct",
|
|
"- Scan media library manually"
|
|
],
|
|
'monitoring': [
|
|
"",
|
|
"**Metrics not collecting**",
|
|
"- Check target endpoints are accessible",
|
|
"- Verify configuration syntax",
|
|
"- Check network connectivity"
|
|
],
|
|
'security': [
|
|
"",
|
|
"**Authentication issues**",
|
|
"- Verify credentials are correct",
|
|
"- Check LDAP/SSO configuration",
|
|
"- Review authentication logs"
|
|
]
|
|
}
|
|
|
|
issues = common_issues.copy()
|
|
if category in category_issues:
|
|
issues.extend(category_issues[category])
|
|
|
|
return '\n'.join(issues)
|
|
|
|
def generate_additional_resources(self, service_name: str, image: str) -> str:
|
|
"""Generate additional resources section."""
|
|
resources = [
|
|
f"- **Official Documentation**: Check the official docs for {service_name}",
|
|
f"- **Docker Hub**: [{image}](https://hub.docker.com/r/{image})" if '/' in image else f"- **Docker Hub**: [Official {service_name}](https://hub.docker.com/_/{image})",
|
|
"- **Community Forums**: Search for community discussions and solutions",
|
|
"- **GitHub Issues**: Check the project's GitHub for known issues"
|
|
]
|
|
|
|
# Add service-specific resources
|
|
service_resources = {
|
|
'plex': [
|
|
"- **Plex Support**: https://support.plex.tv/",
|
|
"- **Plex Forums**: https://forums.plex.tv/"
|
|
],
|
|
'jellyfin': [
|
|
"- **Jellyfin Documentation**: https://jellyfin.org/docs/",
|
|
"- **Jellyfin Forum**: https://forum.jellyfin.org/"
|
|
],
|
|
'grafana': [
|
|
"- **Grafana Documentation**: https://grafana.com/docs/",
|
|
"- **Grafana Community**: https://community.grafana.com/"
|
|
],
|
|
'nextcloud': [
|
|
"- **Nextcloud Documentation**: https://docs.nextcloud.com/",
|
|
"- **Nextcloud Community**: https://help.nextcloud.com/"
|
|
]
|
|
}
|
|
|
|
service_key = service_name.lower().replace('-', '').replace('_', '')
|
|
for key, additional in service_resources.items():
|
|
if key in service_key or service_key in key:
|
|
resources.extend(additional)
|
|
break
|
|
|
|
return '\n'.join(resources)
|
|
|
|
def generate_related_services(self, service_name: str, category: str, host: str) -> str:
|
|
"""Generate related services information."""
|
|
# This would be populated with actual service relationships
|
|
# For now, provide category-based suggestions
|
|
category_related = {
|
|
'media': ['Plex', 'Jellyfin', 'Radarr', 'Sonarr', 'Bazarr', 'Tautulli'],
|
|
'monitoring': ['Grafana', 'Prometheus', 'Uptime Kuma', 'Node Exporter'],
|
|
'productivity': ['Nextcloud', 'Paperless-NGX', 'BookStack', 'Syncthing'],
|
|
'security': ['Vaultwarden', 'Authelia', 'Pi-hole', 'WireGuard'],
|
|
'development': ['GitLab', 'Gitea', 'Jenkins', 'Portainer']
|
|
}
|
|
|
|
related = category_related.get(category, [])
|
|
if not related:
|
|
return f"Other services in the {category} category on {host}"
|
|
|
|
return f"Services REDACTED_APP_PASSWORD {service_name}:\n" + '\n'.join(f"- {service}" for service in related[:5])
|
|
|
|
def get_current_date(self) -> str:
|
|
"""Get current date for documentation."""
|
|
from datetime import datetime
|
|
return datetime.now().strftime("%Y-%m-%d")
|
|
|
|
def generate_all_documentation(self):
|
|
"""Generate documentation for all services."""
|
|
print("🔍 Finding Docker Compose files...")
|
|
compose_files = self.find_compose_files()
|
|
print(f"Found {len(compose_files)} compose files")
|
|
|
|
all_services = {}
|
|
|
|
print("📋 Parsing service configurations...")
|
|
for compose_file in compose_files:
|
|
services = self.parse_compose_file(compose_file)
|
|
all_services.update(services)
|
|
|
|
print(f"Found {len(all_services)} total services")
|
|
|
|
print("📝 Generating individual service documentation...")
|
|
for service_name, service_info in all_services.items():
|
|
print(f" Documenting {service_name}...")
|
|
|
|
# Generate documentation content
|
|
doc_content = self.generate_service_documentation(service_name, service_info)
|
|
|
|
# Write to file
|
|
doc_filename = f"{service_name.lower().replace('_', '-')}.md"
|
|
doc_path = self.docs_path / doc_filename
|
|
|
|
with open(doc_path, 'w', encoding='utf-8') as f:
|
|
f.write(doc_content)
|
|
|
|
print(f"✅ Generated documentation for {len(all_services)} services")
|
|
print(f"📁 Documentation saved to: {self.docs_path}")
|
|
|
|
# Generate index file
|
|
self.generate_service_index(all_services)
|
|
|
|
return len(all_services)
|
|
|
|
def generate_service_index(self, all_services: Dict):
|
|
"""Generate an index file for all services."""
|
|
index_content = f"""# 📚 Individual Service Documentation Index
|
|
|
|
This directory contains detailed documentation for all {len(all_services)} services in the homelab.
|
|
|
|
## 📋 Services by Category
|
|
|
|
"""
|
|
|
|
# Group services by category
|
|
services_by_category = {}
|
|
for service_name, service_info in all_services.items():
|
|
config = service_info['config']
|
|
image = config.get('image', '')
|
|
category = self.categorize_service(service_name, image)
|
|
|
|
if category not in services_by_category:
|
|
services_by_category[category] = []
|
|
|
|
services_by_category[category].append({
|
|
'name': service_name,
|
|
'host': service_info['host'],
|
|
'difficulty': self.get_difficulty_level(service_name, config)
|
|
})
|
|
|
|
# Generate category sections
|
|
for category in sorted(services_by_category.keys()):
|
|
services = sorted(services_by_category[category], key=lambda x: x['name'])
|
|
index_content += f"### {category.title()} ({len(services)} services)\n\n"
|
|
|
|
for service in services:
|
|
filename = f"{service['name'].lower().replace('_', '-')}.md"
|
|
index_content += f"- {service['difficulty']} **[{service['name']}]({filename})** - {service['host']}\n"
|
|
|
|
index_content += "\n"
|
|
|
|
index_content += f"""
|
|
## 📊 Statistics
|
|
|
|
- **Total Services**: {len(all_services)}
|
|
- **Categories**: {len(services_by_category)}
|
|
- **Hosts**: {len(set(s['host'] for s in all_services.values()))}
|
|
|
|
## 🔍 Quick Search
|
|
|
|
Use your browser's search function (Ctrl+F / Cmd+F) to quickly find specific services.
|
|
|
|
---
|
|
|
|
*This index is auto-generated. Last updated: {self.get_current_date()}*
|
|
"""
|
|
|
|
# Write index file
|
|
index_path = self.docs_path / "README.md"
|
|
with open(index_path, 'w', encoding='utf-8') as f:
|
|
f.write(index_content)
|
|
|
|
print(f"📋 Generated service index: {index_path}")
|
|
|
|
if __name__ == "__main__":
|
|
generator = ServiceDocumentationGenerator("/workspace/homelab")
|
|
total_services = generator.generate_all_documentation()
|
|
print(f"\n🎉 Documentation generation complete!")
|
|
print(f"📊 Total services documented: {total_services}")
|