diff --git a/config-templates/dokuwiki/data/pages/architecture/backup.txt b/config-templates/dokuwiki/data/pages/architecture/backup.txt new file mode 100644 index 0000000..74081aa --- /dev/null +++ b/config-templates/dokuwiki/data/pages/architecture/backup.txt @@ -0,0 +1,293 @@ +====== Backup Strategy ====== + +The AI-Homelab implements a comprehensive backup strategy designed for data protection, disaster recovery, and business continuity. + +===== Backup Principles ===== + +**3-2-1 Rule:** + * **3 Copies**: Original + 2 backups + * **2 Media Types**: Different storage technologies + * **1 Offsite**: Geographic separation + +**Recovery Objectives:** + * **RTO (Recovery Time Objective)**: Time to restore service + * **RPO (Recovery Point Objective)**: Maximum data loss acceptable + * **RTO Target**: < 4 hours for critical services + * **RPO Target**: < 1 hour for critical data + +**Backup Types:** + * **Full**: Complete system backup + * **Incremental**: Changes since last backup + * **Differential**: Changes since last full backup + * **Snapshot**: Point-in-time copy + +===== Backup Architecture ===== + +**Primary Backup Solution (Backrest):** +```yaml +services: + backrest: + image: ghcr.io/garethflowers/docker-backrest:latest + volumes: + - ./config/backrest:/config + - /mnt/backups:/backups + - /opt/stacks:/opt/stacks:ro + - /mnt:/mnt:ro + environment: + - BACKREST_CONFIG=/config/config.yml + - BACKREST_SCHEDULE=0 0 * * * +``` + +**Alternative Solution (Duplicati):** +```yaml +services: + duplicati: + image: lscr.io/linuxserver/duplicati:latest + volumes: + - duplicati-config:/config + - duplicati-source:/source:ro + - duplicati-backup:/backup +``` + +===== Backup Categories ===== + +**Configuration Backups:** + * **Source**: `/opt/stacks/*/` + * **Frequency**: Daily + * **Retention**: 30 days + * **Type**: Incremental + * **Critical**: Yes (service definitions) + +**User Data Backups:** + * **Source**: `/mnt/media/`, `/mnt/nextcloud/` + * **Frequency**: Daily + * **Retention**: 90 days + * **Type**: Incremental + * **Critical**: Yes (user files) + +**Database Backups:** + * **Source**: Named Docker volumes + * **Frequency**: Hourly + * **Retention**: 7 days + * **Type**: Snapshot + * **Critical**: Yes (application data) + +**SSL Certificate Backups:** + * **Source**: `/opt/stacks/core/traefik/acme.json` + * **Frequency**: After renewal + * **Retention**: 1 year + * **Type**: Full + * **Critical**: Yes (HTTPS access) + +===== Backup Configuration ===== + +**Backrest Configuration:** +```yaml +version: 1 +schedule: "0 2 * * *" # Daily at 2 AM +repositories: + - path: "/backups/local" + retention: "30d" + - path: "/backups/remote" + retention: "90d" +backups: + - name: "stacks-config" + paths: + - "/opt/stacks" + exclude: + - "*.log" + - "*/cache/*" + - name: "user-data" + paths: + - "/mnt/media" + - "/mnt/nextcloud" + exclude: + - "*/temp/*" + - "*/cache/*" +``` + +**Duplicati Configuration:** + * **Source**: Local directories + * **Destination**: Local/network/cloud storage + * **Encryption**: AES-256 + * **Compression**: ZIP + * **Deduplication**: Block-level + +===== Storage Destinations ===== + +**Local Storage:** + * **Path**: `/mnt/backups/` + * **Type**: External HDD/SSD + * **Encryption**: Filesystem level + * **Access**: Direct mount + +**Network Storage:** + * **Protocol**: NFS/SMB/CIFS + * **Location**: NAS device + * **Redundancy**: RAID protection + * **Security**: VPN access + +**Cloud Storage:** + * **Providers**: AWS S3, Backblaze B2, Google Cloud + * **Encryption**: Client-side + * **Cost**: Pay for storage used + * **Access**: Internet connection + +**Offsite Storage:** + * **Location**: Different geographic location + * **Transport**: Encrypted drives + * **Frequency**: Weekly rotation + * **Security**: Physical security + +===== Encryption & Security ===== + +**Encryption Methods:** + * **Symmetric**: AES-256-GCM + * **Asymmetric**: RSA key pairs + * **Key Management**: Secure key storage + * **Key Rotation**: Regular key updates + +**Security Measures:** + * **Access Control**: Restricted backup access + * **Network Security**: VPN for remote backups + * **Integrity Checks**: SHA-256 verification + * **Audit Logging**: Backup operation logs + +===== Automation & Scheduling ===== + +**Cron Schedules:** +```bash +# Daily backups at 2 AM +0 2 * * * /usr/local/bin/backrest backup + +# Weekly full backup on Sunday +0 3 * * 0 /usr/local/bin/backrest backup --full + +# Monthly archive +0 4 1 * * /usr/local/bin/backrest archive +``` + +**Monitoring:** + * **Success/Failure**: Email notifications + * **Size Tracking**: Storage usage monitoring + * **Performance**: Backup duration tracking + * **Health Checks**: Integrity verification + +===== Recovery Procedures ===== + +**File-Level Recovery:** +```bash +# List snapshots +restic snapshots + +# Restore specific file +restic restore latest --target /tmp/restore --path /opt/stacks/config.yml + +# Restore to original location +restic restore latest --target / --path /opt/stacks +``` + +**Volume Recovery:** +```bash +# Stop service +docker compose down + +# Restore volume +docker run --rm -v restored-volume:/data -v /backups:/backup busybox tar xzf /backup/volume.tar.gz -C / + +# Restart service +docker compose up -d +``` + +**System Recovery:** + 1. **Boot from installation media** + 2. **Restore base system** + 3. **Install Docker** + 4. **Restore configurations** + 5. **Restore user data** + 6. **Verify services** + +===== Testing & Validation ===== + +**Regular Testing:** + * **Monthly**: File restoration tests + * **Quarterly**: Volume recovery tests + * **Annually**: Full system recovery + * **After Changes**: Configuration updates + +**Validation Checks:** +```bash +# Verify backup integrity +restic check + +# List backup contents +restic ls latest + +# Compare file counts +find /original -type f | wc -l +restic ls latest | wc -l +``` + +**Performance Monitoring:** + * **Backup Duration**: Track completion times + * **Success Rate**: Monitor failure rates + * **Storage Growth**: Track backup size trends + * **Recovery Time**: Measure restoration speed + +===== Disaster Recovery ===== + +**Disaster Scenarios:** + * **Hardware Failure**: Drive/server replacement + * **Data Corruption**: File system damage + * **Cyber Attack**: Ransomware recovery + * **Site Disaster**: Complete site loss + +**Recovery Strategies:** + * **Cold Standby**: Pre-configured backup server + * **Cloud Recovery**: Infrastructure as Code + * **Data Center**: Professional recovery services + * **Insurance**: Cyber liability coverage + +**Business Continuity:** + * **Critical Services**: < 1 hour RTO + * **Important Services**: < 4 hours RTO + * **Standard Services**: < 24 hours RTO + * **Acceptable Data Loss**: < 1 hour RPO + +===== Cost Optimization ===== + +**Storage Costs:** + * **Local**: Low initial cost, high maintenance + * **Network**: Medium cost, shared resources + * **Cloud**: Pay-as-you-go, scalable + * **Offsite**: Security vs accessibility trade-off + +**Optimization Strategies:** + * **Compression**: Reduce storage requirements + * **Deduplication**: Eliminate redundant data + * **Tiering**: Move old data to cheaper storage + * **Retention Policies**: Delete unnecessary backups + +===== Compliance & Auditing ===== + +**Regulatory Requirements:** + * **Data Retention**: Industry-specific rules + * **Encryption Standards**: FIPS compliance + * **Access Logging**: Audit trail requirements + * **Testing Frequency**: Regulatory testing schedules + +**Audit Procedures:** + * **Backup Logs**: Operation history + * **Access Logs**: Who accessed backups + * **Change Logs**: Configuration changes + * **Test Results**: Recovery test documentation + +**Documentation:** + * **Procedures**: Step-by-step recovery guides + * **Contacts**: Emergency contact information + * **Dependencies**: Required resources and access + * **Testing**: Regular test schedules and results + +This backup strategy ensures your homelab data remains protected and recoverable in any scenario. + +**Next:** Explore [[services:start|Service Management]] or learn about [[development:start|Contributing]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/architecture/networking.txt b/config-templates/dokuwiki/data/pages/architecture/networking.txt new file mode 100644 index 0000000..5542b00 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/architecture/networking.txt @@ -0,0 +1,329 @@ +====== Network Architecture ====== + +The AI-Homelab uses a sophisticated network architecture designed for security, performance, and scalability. + +===== Network Topology ===== + +``` +Internet + ↓ +[Router/Firewall] + ├── Port 80 (HTTP) → Traefik (Let's Encrypt) + ├── Port 443 (HTTPS) → Traefik (SSL Termination) + └── Port 22 (SSH) → Server (Management) + ↓ +[DuckDNS] Dynamic DNS + ↓ +[Traefik] Reverse Proxy + ├── Authelia SSO Middleware + ├── Service Routing + └── SSL Termination + ↓ +[Docker Networks] + ├── traefik-network (Web Services) + ├── homelab-network (Internal) + ├── media-network (Media Services) + └── service-specific networks +``` + +===== Docker Networks ===== + +**traefik-network (Primary):** + * **Purpose**: All web-accessible services + * **Driver**: Bridge + * **IP Range**: 172.20.0.0/16 + * **External Access**: Yes (via Traefik) + +**homelab-network (Internal):** + * **Purpose**: Internal service communication + * **Driver**: Bridge + * **IP Range**: 172.21.0.0/16 + * **External Access**: No + +**media-network:** + * **Purpose**: Media service isolation + * **Driver**: Bridge + * **IP Range**: 172.22.0.0/16 + * **External Access**: Via Traefik + +**dockerproxy-network:** + * **Purpose**: Docker socket proxy + * **Driver**: Bridge + * **Security**: Restricted access + +===== Traefik Routing ===== + +**Entry Points:** +```yaml +entryPoints: + web: + address: ":80" + http: + redirections: + entryPoint: + to: websecure + scheme: https + websecure: + address: ":443" + http: + tls: + certResolver: letsencrypt +``` + +**Router Configuration:** +```yaml +http: + routers: + service-router: + rule: "Host(`service.yourdomain.duckdns.org`)" + entryPoints: + - websecure + service: service-name + tls: + certResolver: letsencrypt + middlewares: + - authelia@docker +``` + +**Service Discovery:** +```yaml +http: + services: + service-name: + loadBalancer: + servers: + - url: "http://container-name:port" +``` + +===== SSL/TLS Configuration ===== + +**Certificate Resolver:** +```yaml +certificatesResolvers: + letsencrypt: + acme: + email: your-email@example.com + storage: /acme.json + dnsChallenge: + provider: duckdns + delayBeforeCheck: 30 +``` + +**Wildcard Certificate:** + * **Domain**: `*.yourdomain.duckdns.org` + * **Provider**: Let's Encrypt + * **Challenge**: DNS-01 (DuckDNS) + * **Validity**: 90 days + * **Renewal**: Automatic + +**Security Headers:** +```yaml +middlewares: + security-headers: + headers: + stsSeconds: 31536000 + stsIncludeSubdomains: true + stsPreload: true + forceSTSHeader: true + contentTypeNosniff: true + browserXssFilter: true + referrerPolicy: "strict-origin-when-cross-origin" + permissionsPolicy: "geolocation=(), microphone=(), camera=()" +``` + +===== Authelia Integration ===== + +**SSO Middleware:** +```yaml +middlewares: + authelia: + forwardAuth: + address: "http://authelia:9091/api/verify?rd=https://auth.yourdomain.duckdns.org/" + trustForwardHeader: true + authResponseHeaders: + - "Remote-User" + - "Remote-Groups" + - "Remote-Name" + - "Remote-Email" +``` + +**Access Control Rules:** +```yaml +access_control: + default_policy: deny + rules: + - domain: "*.yourdomain.duckdns.org" + policy: two_factor + - domain: "jellyfin.yourdomain.duckdns.org" + policy: bypass + - domain: "plex.yourdomain.duckdns.org" + policy: bypass +``` + +===== VPN Integration ===== + +**Gluetun Network Mode:** +```yaml +services: + qbittorrent: + network_mode: "service:gluetun" + depends_on: + - gluetun +``` + +**Port Mapping:** +```yaml +gluetun: + ports: + - "8080:8080" # qBittorrent Web UI + - "6881:6881" # Torrent port + - "6881:6881/udp" +``` + +**VPN Routing:** + * **Provider**: Surfshark (configurable) + * **Protocol**: WireGuard/OpenVPN + * **Kill Switch**: Prevents IP leaks + * **Port Forwarding**: Automatic + +===== Firewall Configuration ===== + +**UFW Rules (Automatic):** +```bash +# Allow SSH +sudo ufw allow ssh + +# Allow HTTP/HTTPS +sudo ufw allow 80 +sudo ufw allow 443 + +# Enable firewall +sudo ufw enable + +# Default deny +sudo ufw default deny incoming +sudo ufw default allow outgoing +``` + +**Docker Security:** + * **No privileged containers** + * **Non-root user execution** + * **Minimal port exposure** + * **Network isolation** + +===== External Service Proxying ===== + +**Traefik File Provider:** +```yaml +http: + routers: + external-service: + rule: "Host(`external.yourdomain.duckdns.org`)" + service: external-service + middlewares: + - authelia@docker + services: + external-service: + loadBalancer: + servers: + - url: "http://192.168.1.100:8123" +``` + +**Use Cases:** + * **Home Assistant** on Raspberry Pi + * **NAS devices** (TrueNAS, Unraid) + * **Network printers** and IoT devices + * **Legacy applications** + +===== DNS Configuration ===== + +**DuckDNS Setup:** + * **Update Interval**: Every 5 minutes + * **API Token**: Stored in `.env` + * **Domains**: yourdomain.duckdns.org + * **Wildcard**: *.yourdomain.duckdns.org + +**Pi-hole Integration:** + * **Upstream DNS**: Quad9, Cloudflare + * **Ad Blocking**: Enabled + * **Local DNS**: Service discovery + * **DHCP**: Optional + +===== Network Troubleshooting ===== + +**Connectivity Issues:** +```bash +# Check network connectivity +ping -c 4 8.8.8.8 + +# Test DNS resolution +nslookup yourdomain.duckdns.org + +# Check port forwarding +curl -I http://your-external-ip +``` + +**Docker Network Issues:** +```bash +# List networks +docker network ls + +# Inspect network +docker network inspect traefik-network + +# Check container connectivity +docker exec container-name ping traefik +``` + +**SSL Certificate Problems:** +```bash +# Check certificate +echo | openssl s_client -connect yourdomain.duckdns.org:443 -servername service.yourdomain.duckdns.org 2>/dev/null | openssl x509 -noout -subject -dates + +# View Traefik logs +docker logs traefik | grep certificate +``` + +**Authelia Issues:** +```bash +# Check Authelia logs +docker logs authelia + +# Test authentication +curl -k https://auth.yourdomain.duckdns.org/api/state +``` + +===== Performance Optimization ===== + +**Connection Pooling:** + * **Keep-Alive**: Persistent connections + * **Connection Reuse**: Reduce overhead + * **Load Balancing**: Distribute traffic + +**Caching:** + * **Browser Caching**: Static assets + * **Reverse Proxy**: Dynamic content + * **DNS Caching**: Pi-hole + +**Compression:** + * **Gzip**: Text compression + * **Brotli**: Advanced compression + * **Media**: No compression (already compressed) + +===== Monitoring ===== + +**Network Monitoring:** + * **Traefik Dashboard**: Routing metrics + * **Authelia Logs**: Authentication events + * **Pi-hole Stats**: DNS queries + * **Uptime Kuma**: Service availability + +**Traffic Analysis:** + * **Request Logs**: Access patterns + * **Error Rates**: Service health + * **Response Times**: Performance metrics + * **Bandwidth Usage**: Network utilization + +This network architecture provides secure, efficient, and scalable connectivity for all homelab services. + +**Next:** Learn about [[architecture:security|Security Architecture]] or [[architecture:storage|Storage Strategy]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/architecture/overview.txt b/config-templates/dokuwiki/data/pages/architecture/overview.txt new file mode 100644 index 0000000..f4f28da --- /dev/null +++ b/config-templates/dokuwiki/data/pages/architecture/overview.txt @@ -0,0 +1,298 @@ +====== System Architecture ====== + +The AI-Homelab is built on a production-ready, scalable architecture designed for reliability, security, and ease of management. + +===== Core Principles ===== + +**Infrastructure as Code:** + * All services defined in Docker Compose files + * Configuration managed through YAML files + * Version control with Git + * Reproducible deployments + +**Security First:** + * SSO protection for admin interfaces + * Automatic HTTPS with Let's Encrypt + * VPN routing for downloads + * Network isolation and segmentation + +**Scalability:** + * Resource limits prevent exhaustion + * Lazy loading reduces resource usage + * Modular service architecture + * Easy addition of new services + +**Observability:** + * Comprehensive logging + * Metrics collection + * Health monitoring + * Alerting capabilities + +===== Network Architecture ===== + +``` +Internet + ↓ +[Router] Port Forwarding (80, 443) + ↓ +[DuckDNS] Dynamic DNS Updates + ↓ +[Traefik] Reverse Proxy + SSL Termination + ↓ +[Authelia] SSO Authentication + ↓ +[Docker Services] Isolated Containers +``` + +**Network Layers:** + +**External Access:** + * **DuckDNS**: Dynamic DNS service + * **Port Forwarding**: 80/443 to Traefik + * **SSL Termination**: Wildcard certificate + +**Reverse Proxy:** + * **Traefik**: Routes traffic to services + * **Authelia**: SSO middleware + * **Load Balancing**: Service discovery + +**Service Networks:** + * **traefik-network**: All web services + * **homelab-network**: Internal communication + * **media-network**: Media services + * **isolated networks**: Security segmentation + +===== Service Architecture ===== + +**Core Stack (Essential Infrastructure):** + * **DuckDNS**: DNS updates every 5 minutes + * **Traefik**: HTTP routing and SSL + * **Authelia**: Authentication and authorization + * **Gluetun**: VPN client for downloads + * **Sablier**: Lazy loading service + +**Infrastructure Stack:** + * **Dockge**: Primary management interface + * **Pi-hole**: Network-wide DNS and ad blocking + * **Dozzle**: Live Docker log viewer + * **Glances**: System resource monitoring + +**Service Categories:** + +**Media Services:** + * **Jellyfin/Plex**: Media servers with transcoding + * **qBittorrent**: Torrent client (VPN routed) + * **Sonarr/Radarr**: Download automation + * **Prowlarr**: Indexer management + +**Productivity Services:** + * **Nextcloud**: File synchronization + * **Gitea**: Git service and CI/CD + * **BookStack**: Documentation platform + * **WordPress**: Blogging platform + +**Monitoring & Observability:** + * **Grafana**: Dashboard and visualization + * **Prometheus**: Metrics collection + * **Uptime Kuma**: Status monitoring + * **Loki**: Log aggregation + +===== Storage Architecture ===== + +**Configuration Storage:** +``` +/opt/stacks/ +├── core/ # Core infrastructure +├── infrastructure/ # Management tools +├── media/ # Media services +├── productivity/ # Office tools +└── monitoring/ # Observability +``` + +**Data Storage Strategy:** + +**Small Data (< 50GB):** + * **Location**: `/opt/stacks/stack-name/config/` + * **Type**: Bind mounts + * **Backup**: Included in configuration backups + +**Large Data (> 50GB):** + * **Location**: `/mnt/media/`, `/mnt/downloads/`, `/mnt/backups/` + * **Type**: External mounts + * **Backup**: Separate backup strategies + +**Database Storage:** + * **Type**: Named Docker volumes + * **Location**: Docker managed + * **Backup**: Volume snapshots + +===== Security Architecture ===== + +**Authentication & Authorization:** + +**Authelia SSO:** + * **Protocol**: SAML, OpenID Connect + * **Storage**: File-based user database + * **2FA**: TOTP, WebAuthn support + * **Policies**: Domain-based access control + +**Service Authentication:** + * **Admin Services**: Authelia protected + * **Media Services**: Bypass for app compatibility + * **APIs**: Token-based authentication + +**Network Security:** + * **Firewall**: UFW with minimal ports + * **SSL/TLS**: End-to-end encryption + * **VPN**: Download traffic protection + * **Isolation**: Docker network segmentation + +===== Deployment Architecture ===== + +**Two-Phase Deployment:** + +**Phase 1: Setup** +```bash +sudo ./scripts/setup-homelab.sh +``` + * System preparation + * Docker installation + * Authelia configuration + * Infrastructure setup + +**Phase 2: Deployment** +```bash +sudo ./scripts/deploy-homelab.sh +``` + * Core stack deployment + * SSL certificate generation + * Infrastructure services + * Health verification + +**Service Deployment:** + * **Dockge**: Web-based stack management + * **Manual**: Docker Compose commands + * **Automated**: CI/CD pipelines + +===== Resource Management ===== + +**Resource Limits:** +```yaml +deploy: + resources: + limits: + cpus: '2.0' + memory: 4G + reservations: + cpus: '0.5' + memory: 1G +``` + +**Resource Allocation Strategy:** + * **Core Services**: Minimal resources (0.1-0.5 CPU, 64MB-256MB RAM) + * **Web Services**: Moderate resources (1-2 CPU, 1-4GB RAM) + * **Media Services**: High resources (2-4 CPU, 4-8GB RAM) + * **Background Services**: Variable based on workload + +**Lazy Loading:** + * **Sablier**: On-demand service startup + * **Resource Savings**: 50-80% reduction in idle usage + * **Automatic Scaling**: Services start when accessed + +===== Monitoring Architecture ===== + +**Metrics Collection:** + * **Prometheus**: Time-series metrics + * **Node Exporter**: System metrics + * **cAdvisor**: Container metrics + * **Custom Exporters**: Service-specific metrics + +**Logging:** + * **Dozzle**: Real-time log viewer + * **Loki**: Log aggregation + * **Promtail**: Log shipping + * **Structured Logging**: JSON format + +**Alerting:** + * **Uptime Kuma**: Service availability + * **Grafana**: Threshold-based alerts + * **Email/SMS**: Notification channels + +===== Backup Architecture ===== + +**Backup Strategy:** + * **Backrest**: Primary backup solution (Restic) + * **Duplicati**: Alternative encrypted backups + * **Automated**: Scheduled backups + * **Encrypted**: AES-256 encryption + +**Backup Types:** + * **Configuration**: `/opt/stacks/` directories + * **User Data**: Service volumes and mounts + * **SSL Certificates**: `/opt/stacks/core/traefik/acme.json` + * **Databases**: Volume snapshots + +**Recovery:** + * **Point-in-time**: Versioned backups + * **Bare metal**: Complete system recovery + * **Service-level**: Individual service restoration + +===== High Availability ===== + +**Redundancy:** + * **Load Balancing**: Traefik distributes traffic + * **Health Checks**: Automatic service monitoring + * **Failover**: Automatic service restart + * **Backups**: Multiple backup locations + +**Scalability:** + * **Horizontal**: Multiple service instances + * **Vertical**: Resource scaling + * **Storage**: Distributed storage options + * **Network**: High-bandwidth connections + +===== Development Architecture ===== + +**AI Integration:** + * **GitHub Copilot**: Intelligent assistance + * **Copilot Instructions**: Context-aware guidance + * **Automated Configuration**: AI-generated compose files + * **Documentation**: AI-maintained wiki + +**Version Control:** + * **Git**: Source code management + * **Branches**: Feature development + * **Tags**: Release versioning + * **CI/CD**: Automated testing and deployment + +===== Performance Optimization ===== + +**Caching:** + * **Browser Caching**: Static asset optimization + * **Database Caching**: Query result caching + * **CDN**: Content delivery networks + * **Reverse Proxy**: Traefik caching + +**Optimization Techniques:** + * **Compression**: Gzip/Brotli compression + * **Minification**: Asset optimization + * **Lazy Loading**: On-demand resource loading + * **Connection Pooling**: Database optimization + +===== Compliance & Governance ===== + +**Security Standards:** + * **SSL/TLS**: Industry standard encryption + * **Access Control**: Least privilege principle + * **Audit Logging**: Comprehensive activity logs + * **Regular Updates**: Security patch management + +**Data Protection:** + * **Encryption**: Data at rest and in transit + * **Backup Encryption**: Secure offsite storage + * **Privacy**: Minimal data collection + * **Retention**: Configurable data lifecycle + +This architecture provides a solid foundation for a production-ready homelab that can scale with your needs while maintaining security and reliability. + +**Next:** Learn about [[architecture:networking|Network Architecture]] or explore [[services:start|Available Services]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/architecture/security.txt b/config-templates/dokuwiki/data/pages/architecture/security.txt new file mode 100644 index 0000000..d124b1a --- /dev/null +++ b/config-templates/dokuwiki/data/pages/architecture/security.txt @@ -0,0 +1,299 @@ +====== Security Architecture ====== + +The AI-Homelab implements a comprehensive security model based on defense in depth, zero trust principles, and industry best practices. + +===== Security Principles ===== + +**Defense in Depth:** + * **Multiple Layers**: Network, application, and data security + * **Fail-Safe Defaults**: Secure by default, explicit opt-out + * **Least Privilege**: Minimal required permissions + * **Continuous Monitoring**: Real-time threat detection + +**Zero Trust:** + * **Never Trust**: Verify every access request + * **Assume Breach**: Design for compromised systems + * **Micro-Segmentation**: Isolate services and data + * **Continuous Verification**: Ongoing authentication + +**Compliance:** + * **Data Protection**: Encryption at rest and in transit + * **Access Control**: Role-based and attribute-based access + * **Audit Logging**: Comprehensive activity tracking + * **Regular Updates**: Security patch management + +===== Authentication & Authorization ===== + +**Authelia SSO System:** + +**Architecture:** + * **Protocol**: OpenID Connect, SAML 2.0 + * **Storage**: File-based user database + * **Session Management**: Secure JWT tokens + * **Multi-Factor**: TOTP, WebAuthn, Push notifications + +**User Management:** +```yaml +users: + admin: + displayname: Administrator + password: $argon2id$... + email: admin@yourdomain.duckdns.org + groups: + - admins + - dev +``` + +**Access Policies:** +```yaml +access_control: + default_policy: deny + rules: + # Admin services require 2FA + - domain: "*.yourdomain.duckdns.org" + policy: two_factor + subject: + - "group:admins" + + # Media services bypass SSO + - domain: "jellyfin.yourdomain.duckdns.org" + policy: bypass + + # API access with tokens + - domain: "*.yourdomain.duckdns.org" + policy: one_factor + resources: + - "^/api/.*" +``` + +**Session Security:** + * **Expiration**: 8 hour sessions + * **Inactivity Timeout**: 10 minute timeout + * **Secure Cookies**: HttpOnly, Secure, SameSite + * **CSRF Protection**: Token-based validation + +===== SSL/TLS Encryption ===== + +**Certificate Management:** + * **Authority**: Let's Encrypt (trusted CA) + * **Type**: Wildcard ECDSA certificate + * **Domains**: *.yourdomain.duckdns.org + * **Renewal**: Automatic (30 days before expiry) + +**SSL Configuration:** +```yaml +tls: + certificates: + - certFile: /ssl/cert.pem + keyFile: /ssl/private.key + options: + default: + minVersion: VersionTLS12 + cipherSuites: + - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 + - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 + sniStrict: true +``` + +**Security Headers:** +```yaml +headers: + # Prevent clickjacking + customResponseHeaders: + X-Frame-Options: "SAMEORIGIN" + X-Content-Type-Options: "nosniff" + Referrer-Policy: "strict-origin-when-cross-origin" + Permissions-Policy: "geolocation=(), microphone=(), camera=()" + + # HSTS (HTTP Strict Transport Security) + stsSeconds: 31536000 + stsIncludeSubdomains: true + stsPreload: true +``` + +===== Network Security ===== + +**Firewall Configuration:** + * **UFW**: Uncomplicated Firewall + * **Default Policy**: Deny all incoming + * **Allowed Ports**: 22 (SSH), 80 (HTTP), 443 (HTTPS) + * **Docker Isolation**: Container network segmentation + +**Network Segmentation:** + * **traefik-network**: Web-facing services + * **homelab-network**: Internal services + * **media-network**: Media services + * **isolated-networks**: High-security services + +**VPN Protection:** + * **Gluetun**: VPN client container + * **Provider**: Surfshark (configurable) + * **Protocol**: WireGuard (preferred) + * **Kill Switch**: Prevents IP leaks + +===== Container Security ===== + +**Docker Security Best Practices:** + * **Non-root Users**: PUID/PGID environment variables + * **No Privileged Containers**: Minimal capabilities + * **Read-only Filesystems**: Where possible + * **Resource Limits**: CPU and memory constraints + +**Security Scanning:** +```yaml +# Trivy vulnerability scanning +docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \ + aquasec/trivy image your-image:latest + +# Container security audit +docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \ + docker/docker-bench-security +``` + +**Image Security:** + * **Official Images**: LinuxServer.io preferred + * **Version Pinning**: Specific version tags + * **SBOM**: Software Bill of Materials + * **Signature Verification**: Image signing + +===== Data Protection ===== + +**Encryption at Rest:** + * **SSL Certificates**: Encrypted storage + * **User Data**: Service-specific encryption + * **Backups**: AES-256 encryption + * **Secrets**: Environment variable protection + +**Encryption in Transit:** + * **HTTPS**: End-to-end encryption + * **API Communication**: TLS 1.2+ + * **Database Connections**: SSL/TLS + * **VPN Tunneling**: WireGuard/OpenVPN + +**Data Classification:** + * **Public**: No encryption required + * **Internal**: TLS encryption + * **Sensitive**: Additional encryption layers + * **Critical**: Multi-layer encryption + +===== Access Control ===== + +**Role-Based Access Control (RBAC):** +```yaml +# Authelia groups +groups: + admins: + - admin + users: + - user1 + - user2 + media: + - family +``` + +**Service-Level Permissions:** + * **Nextcloud**: User and group permissions + * **Gitea**: Repository access control + * **Grafana**: Dashboard permissions + * **API Keys**: Scoped access tokens + +**Network Access Control:** + * **IP Whitelisting**: Restrict by IP address + * **Geo-blocking**: Country-based restrictions + * **Rate Limiting**: Prevent brute force attacks + * **Fail2Ban**: SSH protection + +===== Monitoring & Auditing ===== + +**Security Monitoring:** + * **Authentication Logs**: Authelia events + * **Access Logs**: Traefik requests + * **System Logs**: Docker and system events + * **Intrusion Detection**: Pattern matching + +**Audit Logging:** +```yaml +# Loki log aggregation +scrape_configs: + - job_name: 'authelia' + static_configs: + - targets: ['authelia:9091'] + relabel_configs: + - source_labels: [__address__] + target_label: __param_target + - source_labels: [__param_target] + target_label: instance + - target_label: __address__ + replacement: localhost:3100 +``` + +**Alerting:** + * **Failed Logins**: Brute force detection + * **Certificate Expiry**: SSL renewal warnings + * **Service Downtime**: Availability monitoring + * **Security Events**: Suspicious activity + +===== Threat Mitigation ===== + +**Common Threats:** + * **Brute Force**: Rate limiting, 2FA + * **SQL Injection**: Parameterized queries + * **XSS**: Content Security Policy + * **CSRF**: Token validation + +**Incident Response:** + 1. **Detection**: Monitoring alerts + 2. **Assessment**: Determine impact + 3. **Containment**: Isolate affected systems + 4. **Recovery**: Restore from backups + 5. **Lessons Learned**: Update policies + +**Backup Security:** + * **Encryption**: AES-256-GCM + * **Integrity**: SHA-256 checksums + * **Retention**: Configurable policies + * **Testing**: Regular restoration tests + +===== Compliance & Governance ===== + +**Security Standards:** + * **OWASP**: Web application security + * **NIST**: Cybersecurity framework + * **ISO 27001**: Information security + * **GDPR**: Data protection + +**Regular Assessments:** + * **Vulnerability Scanning**: Weekly + * **Penetration Testing**: Monthly + * **Security Audits**: Quarterly + * **Compliance Reviews**: Annual + +**Documentation:** + * **Security Policies**: Access and usage rules + * **Incident Response**: Procedures and contacts + * **Change Management**: Update procedures + * **Training**: Security awareness + +===== Advanced Security ===== + +**Zero Trust Network Access (ZTNA):** + * **Identity-Based**: User and device verification + * **Context-Aware**: Risk-based access + * **Micro-Segmentation**: Service isolation + * **Continuous Monitoring**: Real-time assessment + +**Secrets Management:** + * **Environment Variables**: Runtime secrets + * **Docker Secrets**: Swarm mode secrets + * **External Vaults**: HashiCorp Vault integration + * **Key Rotation**: Automatic secret renewal + +**Intrusion Detection:** + * **Network IDS**: Traffic analysis + * **Host IDS**: System monitoring + * **Log Analysis**: Pattern detection + * **SIEM Integration**: Centralized logging + +This security architecture provides comprehensive protection for your homelab while maintaining usability and performance. + +**Next:** Learn about [[architecture:storage|Storage Strategy]] or [[architecture:backup|Backup Strategy]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/architecture/storage.txt b/config-templates/dokuwiki/data/pages/architecture/storage.txt new file mode 100644 index 0000000..07712a9 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/architecture/storage.txt @@ -0,0 +1,291 @@ +====== Storage Architecture ====== + +The AI-Homelab implements a comprehensive storage strategy designed for performance, reliability, and scalability. + +===== Storage Principles ===== + +**Data Classification:** + * **Configuration**: Application settings and metadata + * **User Data**: Files, documents, media + * **System Data**: Logs, caches, temporary files + * **Backup Data**: Archived copies and snapshots + +**Storage Tiers:** + * **Hot**: Frequently accessed data (SSD) + * **Warm**: Regularly accessed data (HDD) + * **Cold**: Archive data (external storage) + * **Offline**: Long-term retention (tape/offsite) + +**Performance Optimization:** + * **Caching**: In-memory data acceleration + * **Compression**: Storage space optimization + * **Deduplication**: Eliminate redundant data + * **Tiering**: Automatic data placement + +===== Directory Structure ===== + +**System Storage (/opt/stacks/):** +``` +/opt/stacks/ +├── core/ # Core infrastructure +│ ├── traefik/ # Reverse proxy config +│ ├── authelia/ # SSO configuration +│ ├── duckdns/ # DNS updater +│ └── gluetun/ # VPN client +├── infrastructure/ # Management tools +├── media/ # Media services +├── productivity/ # Office applications +├── monitoring/ # Observability stack +└── utilities/ # Helper services +``` + +**Data Storage (/mnt/):** +``` +/mnt/ +├── media/ # Movies, TV, music +│ ├── movies/ +│ ├── tv/ +│ └── music/ +├── downloads/ # Torrent downloads +│ ├── complete/ +│ └── incomplete/ +├── backups/ # Backup archives +├── nextcloud/ # Cloud storage +├── git/ # Git repositories +└── surveillance/ # Camera footage +``` + +===== Docker Storage ===== + +**Volume Types:** + +**Named Volumes (Managed):** +```yaml +volumes: + database-data: + driver: local +``` + * **Pros**: Docker managed, portable, backup-friendly + * **Cons**: Less direct access, filesystem overhead + * **Use**: Databases, application data + +**Bind Mounts (Direct):** +```yaml +volumes: + - ./config:/config + - /mnt/media:/media +``` + * **Pros**: Direct filesystem access, performance + * **Cons**: Host-dependent, permission management + * **Use**: Configuration, large media files + +**tmpfs (Memory):** +```yaml +tmpfs: + - /tmp/cache +``` + * **Pros**: High performance, automatic cleanup + * **Cons**: Volatile, memory usage + * **Use**: Caches, temporary files + +**Storage Drivers:** + * **overlay2**: Modern union filesystem + * **btrfs**: Advanced features (snapshots, compression) + * **zfs**: Enterprise-grade (snapshots, deduplication) + +===== Service Storage Patterns ===== + +**Configuration Storage:** +```yaml +services: + service-name: + volumes: + - ./config/service-name:/config + - service-data:/data +``` + * **Config**: Bind mount in stack directory + * **Data**: Named volume for persistence + * **Permissions**: PUID/PGID for access control + +**Media Storage:** +```yaml +services: + jellyfin: + volumes: + - ./config/jellyfin:/config + - jellyfin-cache:/cache + - /mnt/media:/media:ro + - /mnt/transcode:/transcode +``` + * **Media**: Read-only external mount + * **Transcode**: Temporary processing space + * **Cache**: Named volume for performance + +**Database Storage:** +```yaml +services: + postgres: + volumes: + - postgres-data:/var/lib/postgresql/data + environment: + - POSTGRES_DB=homelab + - POSTGRES_USER=homelab + - POSTGRES_PASSWORD=${POSTGRES_PASSWORD} +``` + * **Data**: Named volume for persistence + * **Backups**: Volume snapshots + * **Performance**: Proper indexing + +===== Backup Storage ===== + +**Backrest (Primary):** +```yaml +services: + backrest: + volumes: + - ./config/backrest:/config + - /mnt/backups:/backups + - /opt/stacks:/opt/stacks:ro + - /mnt:/mnt:ro +``` + * **Repository**: Local and remote storage + * **Encryption**: AES-256-GCM + * **Deduplication**: Space-efficient + * **Snapshots**: Point-in-time recovery + +**Duplicati (Alternative):** +```yaml +services: + duplicati: + volumes: + - duplicati-config:/config + - duplicati-source:/source:ro + - duplicati-backup:/backup +``` + * **Frontend**: Web-based interface + * **Destinations**: Multiple cloud providers + * **Encryption**: Built-in encryption + * **Scheduling**: Automated backups + +===== Performance Optimization ===== + +**Filesystem Choice:** + * **ext4**: General purpose, reliable + * **btrfs**: Snapshots, compression, RAID + * **ZFS**: Advanced features, data integrity + * **XFS**: High performance, large files + +**RAID Configuration:** + * **RAID 1**: Mirroring (2 drives) + * **RAID 5**: Striping with parity (3+ drives) + * **RAID 10**: Mirroring + striping (4+ drives) + * **RAID Z**: ZFS software RAID + +**Caching Strategies:** + * **Page Cache**: OS-level caching + * **Application Cache**: Service-specific caching + * **CDN**: Content delivery networks + * **Reverse Proxy**: Traefik caching + +===== Monitoring & Maintenance ===== + +**Storage Monitoring:** +```bash +# Disk usage +df -h + +# Docker storage +docker system df + +# Volume usage +docker volume ls +docker volume inspect volume-name +``` + +**Maintenance Tasks:** + * **Cleanup**: Remove unused volumes and images + * **Defragmentation**: Filesystem optimization + * **SMART Monitoring**: Drive health checks + * **Backup Verification**: Integrity testing + +**Health Checks:** + * **Filesystem**: fsck, scrub operations + * **RAID**: Array status monitoring + * **SMART**: Drive error monitoring + * **Backup**: Restoration testing + +===== Capacity Planning ===== + +**Storage Requirements:** + +| Service | Typical Size | Growth Rate | +|---------|-------------|-------------| +| Nextcloud | 100GB+ | High (user files) | +| Jellyfin | 500GB+ | High (media library) | +| Gitea | 10GB+ | Medium (repositories) | +| Grafana | 5GB+ | Low (metrics) | +| Backups | 2x data size | Variable | + +**Scaling Strategies:** + * **Vertical**: Larger drives, more RAM + * **Horizontal**: Multiple storage servers + * **Cloud**: Hybrid cloud storage + * **Archival**: Long-term retention solutions + +===== Security Considerations ===== + +**Encryption:** + * **At Rest**: Filesystem encryption (LUKS) + * **In Transit**: TLS encryption + * **Backups**: Encrypted archives + * **Keys**: Secure key management + +**Access Control:** + * **Permissions**: Proper file permissions + * **SELinux/AppArmor**: Mandatory access control + * **Network**: Isolated storage networks + * **Auditing**: Access logging + +**Data Protection:** + * **RAID**: Redundancy protection + * **Snapshots**: Point-in-time copies + * **Backups**: Offsite copies + * **Testing**: Regular recovery tests + +===== Disaster Recovery ===== + +**Recovery Strategies:** + * **File-level**: Individual file restoration + * **Volume-level**: Docker volume recovery + * **System-level**: Complete system restore + * **Bare-metal**: Full server recovery + +**Business Continuity:** + * **RTO**: Recovery Time Objective + * **RPO**: Recovery Point Objective + * **Testing**: Regular DR exercises + * **Documentation**: Recovery procedures + +**High Availability:** + * **Replication**: Data mirroring + * **Clustering**: Distributed storage + * **Load Balancing**: Access distribution + * **Failover**: Automatic switching + +===== Migration Strategies ===== + +**Storage Migration:** + * **Live Migration**: Zero-downtime moves + * **Offline Migration**: Scheduled maintenance + * **Incremental**: Phased data movement + * **Verification**: Data integrity checks + +**Technology Upgrades:** + * **Filesystem**: ext4 to btrfs/ZFS + * **RAID**: Hardware to software RAID + * **Storage**: Local to network storage + * **Cloud**: Hybrid cloud solutions + +This storage architecture provides reliable, performant, and scalable data management for your homelab. + +**Next:** Learn about [[architecture:backup|Backup Strategy]] or explore [[services:start|Service Management]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/getting_started/access.txt b/config-templates/dokuwiki/data/pages/getting_started/access.txt new file mode 100644 index 0000000..4b70dc0 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/getting_started/access.txt @@ -0,0 +1,251 @@ +====== Access Services ====== + +After deployment, access your homelab services through secure HTTPS URLs. + +===== Service URLs ===== + +All services are accessible at `https://service-name.yourdomain.duckdns.org` + +| Category | Service | URL | Authentication | Purpose | +|----------|---------|-----|----------------|---------| +| **Management** | Dockge | `https://dockge.yourdomain.duckdns.org` | Authelia SSO | Stack management | +| **Management** | Homepage | `https://home.yourdomain.duckdns.org` | Authelia SSO | Service dashboard | +| **Security** | Authelia | `https://auth.yourdomain.duckdns.org` | Direct login | SSO authentication | +| **Infrastructure** | Traefik | `https://traefik.yourdomain.duckdns.org` | Authelia SSO | Reverse proxy dashboard | +| **Infrastructure** | Pi-hole | `http://pihole.yourdomain.duckdns.org` | Authelia SSO | DNS & ad blocking | +| **Infrastructure** | Dozzle | `https://dozzle.yourdomain.duckdns.org` | Authelia SSO | Log viewer | +| **Infrastructure** | Glances | `https://glances.yourdomain.duckdns.org` | Authelia SSO | System monitoring | +| **Media** | Jellyfin | `https://jellyfin.yourdomain.duckdns.org` | None (app access) | Media server | +| **Media** | Plex | `https://plex.yourdomain.duckdns.org` | None (app access) | Media server | +| **Media** | qBittorrent | `https://qbit.yourdomain.duckdns.org` | Authelia SSO | Torrent client | +| **Media Mgmt** | Sonarr | `https://sonarr.yourdomain.duckdns.org` | Authelia SSO | TV automation | +| **Media Mgmt** | Radarr | `https://radarr.yourdomain.duckdns.org` | Authelia SSO | Movie automation | +| **Productivity** | Nextcloud | `https://nextcloud.yourdomain.duckdns.org` | Authelia SSO | File sync | +| **Productivity** | Gitea | `https://git.yourdomain.duckdns.org` | Authelia SSO | Git service | +| **Productivity** | BookStack | `https://docs.yourdomain.duckdns.org` | Authelia SSO | Documentation | +| **Monitoring** | Grafana | `https://grafana.yourdomain.duckdns.org` | Authelia SSO | Dashboards | +| **Monitoring** | Prometheus | `https://prometheus.yourdomain.duckdns.org` | Authelia SSO | Metrics | +| **Monitoring** | Uptime Kuma | `https://status.yourdomain.duckdns.org` | Authelia SSO | Status monitoring | +| **Home Auto** | Home Assistant | `https://ha.yourdomain.duckdns.org` | None (built-in auth) | Home automation | +| **Utilities** | Backrest | `https://backrest.yourdomain.duckdns.org` | Authelia SSO | Backup management | +| **Development** | Code Server | `https://code.yourdomain.duckdns.org` | Authelia SSO | VS Code in browser | + +===== Authentication ===== + +==== Authelia SSO (Single Sign-On) ==== + +**Protected Services:** + * Most admin interfaces require Authelia login + * One login grants access to all protected services + * Supports 2FA (Two-Factor Authentication) + +**Login Process:** + 1. Visit any protected service URL + 2. Redirected to Authelia login page + 3. Enter username and password + 4. (Optional) Enter 2FA code + 5. Redirected back to original service + +**Default Credentials:** + * Username: `admin` (or custom from setup) + * Password: Secure password from setup + +==== Service-Specific Authentication ==== + +**No SSO (Direct Access):** + * **Jellyfin/Plex**: Use service's built-in user management + * **Home Assistant**: Built-in authentication system + * **Nextcloud**: Can use Authelia or built-in auth + +**VPN-Protected Services:** + * **qBittorrent**: Routes through Gluetun VPN + * Access via web UI after Authelia login + +===== Security Features ===== + +==== SSL/TLS Encryption ==== + +**Wildcard Certificate:** + * Covers all `*.yourdomain.duckdns.org` subdomains + * Issued by Let's Encrypt (free) + * Automatic renewal every 90 days + * A+ SSL rating + +**Certificate Details:** + * **Issuer**: Let's Encrypt Authority X3 + * **Algorithm**: ECDSA P-256 + * **Validity**: 90 days + * **Renewal**: Automatic via Traefik + +==== Firewall Protection ==== + +**UFW Configuration:** + * Only ports 80, 443, and 22 (SSH) open + * All other ports blocked + * Docker containers isolated + +**Network Security:** + * Services behind reverse proxy + * No direct container exposure + * VPN routing for downloads + +==== Access Control ==== + +**Authelia Policies:** + * **One Factor**: Username + password + * **Two Factor**: Username + password + TOTP + * **Bypass**: No authentication required + +**Default Policies:** + * Admin services: Two-factor recommended + * Media services: Bypass (app compatibility) + * Public services: Bypass when appropriate + +===== First-Time Access ===== + +==== Configure Authelia ==== + +1. **Access Authelia:** + * URL: `https://auth.yourdomain.duckdns.org` + * Login with admin credentials + +2. **Enable 2FA:** + * Go to **Settings** → **One-Time Password** + * Scan QR code with authenticator app + * Enter verification code + +3. **Configure Access Rules:** + * Edit `/opt/stacks/core/authelia/configuration.yml` + * Modify access policies as needed + +==== Set Up Homepage Dashboard ==== + +1. **Access Homepage:** + * URL: `https://home.yourdomain.duckdns.org` + +2. **Initial Configuration:** + * Click settings icon (gear) + * Add deployed services + * Configure widgets + +3. **API Integration:** + * Add API keys for enhanced widgets + * Configure service integrations + +==== Test Service Access ==== + +**Verification Checklist:** + * [ ] Authelia login works + * [ ] Homepage loads correctly + * [ ] Dockge accessible + * [ ] SSL certificates valid + * [ ] No mixed content warnings + +===== Troubleshooting Access ===== + +==== SSL Certificate Issues ==== + +**"Not Secure" warnings:** + * Wait 2-5 minutes after deployment + * Check DNS propagation: `nslookup yourdomain.duckdns.org` + * Verify ports 80/443 forwarded + * Check Traefik logs: `docker logs traefik` + +**Certificate errors:** +```bash +# Check certificate status +echo | openssl s_client -connect yourdomain.duckdns.org:443 -servername dockge.yourdomain.duckdns.org 2>/dev/null | openssl x509 -noout -subject -dates +``` + +==== Authentication Problems ==== + +**Can't log in to Authelia:** + * Verify username/password + * Check 2FA setup + * Clear browser cache + * Check Authelia logs: `docker logs authelia` + +**Redirect loops:** + * Check Traefik configuration + * Verify middleware labels + * Restart Traefik: `docker restart traefik` + +==== Service Not Accessible ==== + +**404 errors:** + * Service not deployed + * Traefik route not configured + * Wrong subdomain + +**Connection refused:** + * Service not running + * Port mapping issues + * Network connectivity problems + +==== DNS Issues ==== + +**Domain not resolving:** + * Check DuckDNS configuration + * Verify token in `.env` + * Wait for DNS propagation + +**Local network access:** + * Use internal IP for local access + * Configure local DNS overrides + +===== Advanced Access ===== + +==== External Service Proxying ==== + +**Proxy non-Docker services:** + * Raspberry Pi Home Assistant + * NAS devices + * Other network services + +**Configuration:** + * Add routes to `/opt/stacks/core/traefik/dynamic/external.yml` + * Include Authelia middleware + * Test connectivity + +==== VPN Access ==== + +**Remote Access:** + * Configure VPN server (OpenVPN/WireGuard) + * Route traffic through VPN + * Access local services remotely + +==== API Access ==== + +**Service APIs:** + * Most services expose REST APIs + * Use API keys for authentication + * Configure in Homepage widgets + +===== Mobile Access ===== + +**Mobile Apps:** + * **Jellyfin/Plex**: Dedicated mobile apps + * **Nextcloud**: Mobile sync client + * **Home Assistant**: Mobile companion app + * **Bitwarden**: Password manager + +**Browser Access:** + * All services work in mobile browsers + * Responsive design for most interfaces + * Authelia SSO works on mobile + +===== Performance Optimization ===== + +**Loading Speed:** + * Enable HTTP/2 in Traefik + * Use CDN for static assets + * Optimize service configurations + +**Resource Usage:** + * Monitor with Glances + * Set appropriate resource limits + * Use lazy loading for unused services + +Ready to access your services? Start with the [[getting_started:security|Security Setup]] guide. + +**Need help?** Check [[troubleshooting:networking|Network Troubleshooting]] or visit [[https://github.com/kelinfoxy/AI-Homelab/discussions|GitHub Discussions]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/getting_started/deployment.txt b/config-templates/dokuwiki/data/pages/getting_started/deployment.txt new file mode 100644 index 0000000..31e8c2f --- /dev/null +++ b/config-templates/dokuwiki/data/pages/getting_started/deployment.txt @@ -0,0 +1,284 @@ +====== Deployment ====== + +After setup, deploy your homelab services using Dockge or manual commands. + +===== Using Dockge (Recommended) ===== + +**Access Dockge:** + * URL: `https://dockge.yourdomain.duckdns.org` + * Username: `admin` (or your custom username) + * Password: Your secure password from setup + +**Deploy Services:** + 1. Click **"Add Stack"** button + 2. Choose **"From Docker Compose"** + 3. Select a compose file from the repository + 4. Click **"Deploy"** + 5. Monitor deployment in the **"Logs"** tab + +**Available Stacks:** + * `media.yml` - Media services (Jellyfin, qBittorrent) + * `media-management.yml` - Download automation (Sonarr, Radarr) + * `productivity.yml` - Office tools (Nextcloud, Gitea) + * `monitoring.yml` - Observability (Grafana, Prometheus) + * `homeassistant.yml` - Home automation + * `utilities.yml` - Backup and utilities + +===== Manual Deployment ===== + +**Deploy Individual Stacks:** + +```bash +# Navigate to repository +cd ~/AI-Homelab + +# Deploy media services +docker compose -f docker-compose/media.yml up -d + +# Deploy productivity stack +docker compose -f docker-compose/productivity.yml up -d + +# Deploy monitoring +docker compose -f docker-compose/monitoring.yml up -d +``` + +**Check Deployment Status:** + +```bash +# View all running containers +docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" + +# Check specific stack +docker compose -f docker-compose/media.yml ps + +# View logs +docker compose -f docker-compose/media.yml logs -f +``` + +===== Service Access ===== + +After deployment, services are available at: + +| Category | Service | URL | Notes | +|----------|---------|-----|-------| +| **Media** | Jellyfin | `https://jellyfin.yourdomain.duckdns.org` | No SSO (app access) | +| **Media** | qBittorrent | `https://qbit.yourdomain.duckdns.org` | VPN protected | +| **Productivity** | Nextcloud | `https://nextcloud.yourdomain.duckdns.org` | File sync | +| **Productivity** | Gitea | `https://git.yourdomain.duckdns.org` | Git service | +| **Monitoring** | Grafana | `https://grafana.yourdomain.duckdns.org` | Dashboards | +| **Development** | Code Server | `https://code.yourdomain.duckdns.org` | VS Code in browser | + +===== Post-Deployment Configuration ===== + +==== Configure Homepage Dashboard ==== + +1. Visit `https://home.yourdomain.duckdns.org` +2. Click settings (gear icon) +3. Add services to dashboard +4. Configure widgets with API keys + +**Example Widgets:** + * System monitoring (CPU, RAM, disk) + * Service status checks + * Weather information + * Calendar integration + +==== Set Up Backups ==== + +1. Deploy Backrest service +2. Configure backup schedules +3. Set up encryption +4. Test backup restoration + +==== Configure Monitoring ==== + +1. Deploy Grafana and Prometheus +2. Import dashboards +3. Set up alerts +4. Configure data sources + +===== Deployment Order ===== + +**Recommended Deployment Sequence:** + +1. **Core** (deployed automatically) + - DuckDNS, Traefik, Authelia, Gluetun + +2. **Infrastructure** (deployed automatically) + - Dockge, Pi-hole, Dozzle, Glances + +3. **Dashboards** (deployed automatically) + - Homepage, Homarr + +4. **Media Services** + - Jellyfin or Plex + - qBittorrent (VPN routing) + - Sonarr, Radarr, Prowlarr + +5. **Productivity** + - Nextcloud, Gitea, BookStack + +6. **Monitoring** + - Grafana, Prometheus, Uptime Kuma + +7. **Home Automation** + - Home Assistant, Node-RED + +===== Resource Management ===== + +**Monitor Resource Usage:** + +```bash +# Check container resources +docker stats + +# View system resources +docker run --rm -v /proc:/host/proc:ro --net=host codenvy/glances + +# Check disk space +df -h /opt/stacks/ +``` + +**Resource Limits Applied:** + * CPU limits prevent resource exhaustion + * Memory limits protect system stability + * Automatic cleanup of unused resources + +===== Troubleshooting Deployment ===== + +==== Service Won't Start ==== + +**Check Logs:** +```bash +# View service logs +docker compose -f docker-compose/stack.yml logs service-name + +# Follow logs in real-time +docker compose -f docker-compose/stack.yml logs -f service-name +``` + +**Common Issues:** + * Port conflicts + * Missing environment variables + * Network connectivity problems + * Insufficient resources + +==== SSL Certificate Issues ==== + +**Check Certificate Status:** +```bash +# View Traefik logs +docker logs traefik | grep certificate + +# Check certificate file +ls -la /opt/stacks/core/traefik/acme.json +``` + +**Certificate Problems:** + * DNS propagation delay (wait 5-10 minutes) + * DuckDNS token incorrect + * Ports 80/443 not forwarded + * Rate limiting (Let's Encrypt limits) + +==== Network Issues ==== + +**Verify Networks:** +```bash +# List Docker networks +docker network ls + +# Inspect traefik-network +docker network inspect traefik-network +``` + +**Network Troubleshooting:** + * Services not on correct network + * Firewall blocking traffic + * DNS resolution problems + +==== Permission Issues ==== + +**Check File Permissions:** +```bash +# Check stack directory permissions +ls -la /opt/stacks/stack-name/ + +# Check Docker socket permissions +ls -la /var/run/docker.sock +``` + +**Fix Permissions:** +```bash +# Set correct ownership +sudo chown -R $USER:$USER /opt/stacks/stack-name/ + +# Add user to docker group +sudo usermod -aG docker $USER +``` + +===== Scaling and Customization ===== + +==== Add Custom Services ==== + +1. Create new compose file +2. Add Traefik labels for routing +3. Include Authelia middleware +4. Deploy via Dockge + +==== Modify Existing Services ==== + +1. Edit compose file +2. Update environment variables +3. Redeploy service +4. Test functionality + +==== Remove Services ==== + +```bash +# Stop and remove service +docker compose -f docker-compose/stack.yml down + +# Remove with volumes +docker compose -f docker-compose/stack.yml down -v + +# Clean up unused resources +docker system prune +``` + +===== Performance Optimization ===== + +**Hardware Acceleration:** + * Enable NVIDIA GPU for transcoding + * Use SSD storage for databases + * Configure appropriate CPU/memory limits + +**Network Optimization:** + * Use wired connections when possible + * Configure QoS for media streaming + * Optimize DNS resolution + +**Service Optimization:** + * Enable lazy loading for unused services + * Configure appropriate resource limits + * Use efficient Docker images + +===== Backup and Recovery ===== + +**Regular Backups:** + * Configuration files in `/opt/stacks/` + * SSL certificates in `/opt/stacks/core/traefik/` + * User data in service volumes + +**Recovery Process:** + * Restore configuration files + * Redeploy services + * Restore user data from backups + +**Disaster Recovery:** + * Keep backup scripts ready + * Document recovery procedures + * Test restoration regularly + +Ready to deploy? Use Dockge to start deploying services! + +**Need help?** See [[troubleshooting:services|Service Troubleshooting]] or check [[reference:commands|Command Reference]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/getting_started/prerequisites.txt b/config-templates/dokuwiki/data/pages/getting_started/prerequisites.txt new file mode 100644 index 0000000..d8ffd57 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/getting_started/prerequisites.txt @@ -0,0 +1,201 @@ +====== Prerequisites ====== + +Before deploying your AI-Homelab, ensure your system meets these requirements. + +===== System Requirements ===== + +**Minimum Hardware:** + * **CPU**: 2-core processor (4+ cores recommended) + * **RAM**: 4GB minimum (8GB+ recommended) + * **Storage**: 50GB free space (SSD preferred) + * **Network**: Stable internet connection + +**Recommended Hardware:** + * **CPU**: 4+ core processor with virtualization support + * **RAM**: 16GB+ for full stack deployment + * **Storage**: 500GB+ SSD for media and backups + * **GPU**: NVIDIA GPU (optional, for hardware transcoding) + +===== Operating System ===== + +**Supported Systems:** + * **Ubuntu 20.04+** (recommended) + * **Debian 11+** + * **Ubuntu Server** + * **Raspberry Pi OS** (64-bit, for lightweight deployments) + +**Fresh Installation Recommended:** + * Start with a clean OS install + * Avoid pre-installed Docker versions + * Use LTS (Long Term Support) releases + +===== Network Requirements ===== + +**Domain & DNS:** + * **DuckDNS account**: [[https://duckdns.org|Create free account]] + * **Domain**: Choose your subdomain (e.g., `yourname.duckdns.org`) + * **Token**: Get your DuckDNS token from account settings + +**Port Forwarding:** + * **Port 80**: Required for Let's Encrypt HTTP challenge + * **Port 443**: Required for HTTPS traffic + * **Router**: Configure port forwarding to your server + +**Network Access:** + * **Outbound**: Full internet access for updates and services + * **Inbound**: Ports 80/443 forwarded from router + * **Local**: Access to router admin panel (for port forwarding) + +===== Software Prerequisites ===== + +**Required Software:** + * **Git**: Version control system + * **curl/wget**: Download utilities + * **SSH server**: Remote access (usually pre-installed) + +**Optional but Recommended:** + * **VS Code**: With GitHub Copilot extension + * **Docker Desktop**: For local testing (Windows/Mac) + * **NVIDIA drivers**: If using GPU acceleration + +===== Account Setup ===== + +**Required Accounts:** + * **DuckDNS**: Free dynamic DNS service + * Visit [[https://duckdns.org]] + * Create account and subdomain + * Copy your token for configuration + +**Optional Accounts (for specific services):** + * **Surfshark VPN**: For secure downloads + * **GitHub**: For repository access and Copilot + * **Cloud storage**: For offsite backups + +===== Security Considerations ===== + +**Firewall Setup:** + * UFW (Uncomplicated Firewall) will be configured automatically + * Only necessary ports will be opened + * SSH access restricted to key-based authentication + +**SSL Certificates:** + * Let's Encrypt provides free certificates + * Wildcard certificate covers all subdomains + * Automatic renewal every 90 days + +**Access Control:** + * Authelia provides SSO (Single Sign-On) + * 2FA (Two-Factor Authentication) recommended + * Granular access control per service + +===== Pre-Installation Checklist ===== + +**Hardware Check:** + * [ ] Server meets minimum requirements + * [ ] Sufficient storage space available + * [ ] Stable power supply + * [ ] Backup power (UPS) recommended + +**Network Check:** + * [ ] Internet connection stable + * [ ] Router supports port forwarding + * [ ] Ports 80/443 available and forwarded + * [ ] Local IP address known and static + +**Account Setup:** + * [ ] DuckDNS account created + * [ ] Domain chosen and configured + * [ ] DuckDNS token obtained + * [ ] Optional: VPN credentials prepared + +**Software Preparation:** + * [ ] SSH access to server established + * [ ] VS Code installed (optional) + * [ ] GitHub Copilot configured (optional) + +===== Environment Variables ===== + +Create a `.env` file with these variables: + +``` +# Domain Configuration +DOMAIN=yourdomain.duckdns.org +DUCKDNS_TOKEN=your-duckdns-token + +# Optional: VPN Configuration +SURFSHARK_USERNAME=your-vpn-username +SURFSHARK_PASSWORD=your-vpn-password + +# Authelia (auto-generated by setup script) +AUTHELIA_JWT_SECRET=64-char-random-string +AUTHELIA_SESSION_SECRET=64-char-random-string +AUTHELIA_STORAGE_ENCRYPTION_KEY=64-char-random-string + +# User Configuration +PUID=1000 +PGID=1000 +TZ=America/New_York +``` + +**Note:** Authelia secrets are auto-generated by the setup script. Leave them with default values initially. + +===== Testing Your Setup ===== + +**Network Connectivity:** +```bash +# Test internet connection +ping -c 4 8.8.8.8 + +# Test DNS resolution +nslookup duckdns.org + +# Test port forwarding (from external network) +curl -I http://your-external-ip +``` + +**System Resources:** +```bash +# Check available space +df -h / + +# Check memory +free -h + +# Check CPU cores +nproc +``` + +**SSH Access:** +```bash +# Test SSH connection +ssh user@your-server-ip + +# Test sudo access +sudo whoami +``` + +===== Troubleshooting Prerequisites ===== + +**"Permission denied" errors:** + * Ensure you have sudo access + * Check if user is in sudo group + * Try running commands with `sudo` + +**Network connectivity issues:** + * Verify internet connection + * Check firewall settings + * Test DNS resolution + +**Port forwarding problems:** + * Access router admin panel + * Verify ports 80/443 are forwarded + * Check if ISP blocks these ports + +**DuckDNS issues:** + * Verify token is correct + * Check domain is available + * Test DNS updates manually + +Ready to proceed? Continue to [[getting_started:setup|Automated Setup]]. + +**Need Help?** Check the [[troubleshooting:start|Troubleshooting Guide]] or visit [[https://github.com/kelinfoxy/AI-Homelab/discussions|GitHub Discussions]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/getting_started/security.txt b/config-templates/dokuwiki/data/pages/getting_started/security.txt new file mode 100644 index 0000000..97fc79d --- /dev/null +++ b/config-templates/dokuwiki/data/pages/getting_started/security.txt @@ -0,0 +1,245 @@ +====== Security Setup ====== + +Secure your homelab with proper authentication, encryption, and access controls. + +===== Two-Factor Authentication ===== + +**Enable 2FA for Authelia:** + +1. **Access Authelia:** + * URL: `https://auth.yourdomain.duckdns.org` + * Login with admin credentials + +2. **Configure TOTP:** + * Go to **Settings** → **One-Time Password** + * Install authenticator app (Google Authenticator, Authy, etc.) + * Scan QR code or enter secret manually + * Enter verification code to enable + +3. **Backup Codes:** + * Generate backup codes for recovery + * Store securely (encrypted password manager) + * Use only for emergency access + +**2FA Best Practices:** + * Use hardware security keys when possible + * Enable biometric authentication on mobile + * Regularly rotate backup codes + * Test recovery process + +===== Access Control Policies ===== + +**Authelia Configuration:** + * Location: `/opt/stacks/core/authelia/configuration.yml` + +**Default Policies:** +```yaml +access_control: + default_policy: deny + rules: + # Admin services - require 2FA + - domain: "*.yourdomain.duckdns.org" + policy: two_factor + + # Media services - bypass SSO (app compatibility) + - domain: jellyfin.yourdomain.duckdns.org + policy: bypass + - domain: plex.yourdomain.duckdns.org + policy: bypass + + # Home Assistant - bypass (built-in auth) + - domain: ha.yourdomain.duckdns.org + policy: bypass +``` + +**Policy Types:** + * **deny**: Block all access + * **one_factor**: Username + password only + * **two_factor**: Username + password + 2FA + * **bypass**: No authentication required + +===== SSL/TLS Security ===== + +**Certificate Management:** + * **Issuer**: Let's Encrypt (trusted CA) + * **Type**: Wildcard certificate (*.yourdomain.duckdns.org) + * **Algorithm**: ECDSA P-256 with SHA-256 + * **Validity**: 90 days with automatic renewal + +**Security Headers:** + * **HSTS**: HTTP Strict Transport Security + * **CSP**: Content Security Policy + * **X-Frame-Options**: Clickjacking protection + * **X-Content-Type-Options**: MIME sniffing prevention + +**Traefik Security:** +```yaml +# In traefik.yml +http: + middlewares: + security-headers: + headers: + customRequestHeaders: + X-Forwarded-Proto: "https" + customResponseHeaders: + X-Frame-Options: "SAMEORIGIN" + X-Content-Type-Options: "nosniff" + Referrer-Policy: "strict-origin-when-cross-origin" + Permissions-Policy: "geolocation=(), microphone=(), camera=()" +``` + +===== Firewall Configuration ===== + +**UFW Rules (automatically configured):** +```bash +# Allow SSH +sudo ufw allow ssh + +# Allow HTTP/HTTPS +sudo ufw allow 80 +sudo ufw allow 443 + +# Enable firewall +sudo ufw enable +``` + +**Docker Security:** + * Containers run as non-root users + * No privileged containers + * Minimal exposed ports + * Network isolation + +===== Password Security ===== + +**Strong Password Requirements:** + * Minimum 12 characters + * Mix of uppercase, lowercase, numbers, symbols + * No dictionary words or common patterns + * Unique per service + +**Password Manager Integration:** + * Use Bitwarden/Vaultwarden for password storage + * Enable auto-fill for services + * Regular password rotation + * Emergency access setup + +===== VPN and Network Security ===== + +**Download Protection:** + * qBittorrent routes through Gluetun VPN + * All torrent traffic encrypted + * No IP leaks during downloads + +**Network Segmentation:** + * Services isolated in Docker networks + * Database access restricted + * External services proxied through Traefik + +===== Backup Security ===== + +**Encrypted Backups:** + * Use Backrest with encryption + * Store encryption keys securely + * Offsite backup storage + * Regular integrity checks + +**Backup Verification:** +```bash +# Test backup restoration +restic restore latest --target /tmp/restore-test +restic check +``` + +===== Service-Specific Security ===== + +**Nextcloud Security:** + * Enable brute force protection + * Configure trusted domains + * Set up file encryption + * Regular security scans + +**Gitea Security:** + * Disable public registration + * Enable SSH key authentication + * Configure access tokens + * Regular repository backups + +**Database Security:** + * Strong database passwords + * Network isolation + * Regular updates + * Query logging + +===== Monitoring and Alerts ===== + +**Security Monitoring:** + * Enable fail2ban for SSH protection + * Monitor authentication attempts + * Set up intrusion detection + * Log analysis with Loki/Promtail + +**Alert Configuration:** + * Failed login notifications + * Certificate expiration warnings + * Service downtime alerts + * Security vulnerability notifications + +===== Incident Response ===== + +**Security Breach Response:** + 1. **Isolate**: Disconnect affected systems + 2. **Assess**: Determine scope of breach + 3. **Contain**: Change all passwords + 4. **Recover**: Restore from clean backups + 5. **Learn**: Update security policies + +**Emergency Access:** + * Keep backup authentication methods + * Document recovery procedures + * Test incident response plans + * Regular security audits + +===== Advanced Security ===== + +**Certificate Pinning:** + * Pin Let's Encrypt intermediate certificates + * Monitor certificate transparency logs + * Automated certificate validation + +**Zero Trust Architecture:** + * Every access request verified + * Minimal privilege access + * Continuous authentication + * Network micro-segmentation + +**Compliance Considerations:** + * Data encryption at rest and in transit + * Access logging and monitoring + * Regular security assessments + * Privacy-preserving configurations + +===== Security Checklist ===== + +**Initial Setup:** + * [ ] 2FA enabled for all admin accounts + * [ ] Strong, unique passwords everywhere + * [ ] SSL certificates properly configured + * [ ] Firewall rules verified + * [ ] VPN configured for downloads + +**Ongoing Security:** + * [ ] Regular password rotation + * [ ] Security updates applied + * [ ] Backup encryption verified + * [ ] Access logs reviewed + * [ ] Security scans performed + +**Emergency Preparedness:** + * [ ] Backup authentication methods available + * [ ] Incident response plan documented + * [ ] Recovery procedures tested + * [ ] Contact information current + +Your homelab is now secure! Continue to [[architecture:security|Security Architecture]] for detailed technical information. + +**Need help?** Check [[troubleshooting:ssl|SSL Troubleshooting]] or visit [[https://github.com/kelinfoxy/AI-Homelab/discussions|GitHub Discussions]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/getting_started/setup.txt b/config-templates/dokuwiki/data/pages/getting_started/setup.txt new file mode 100644 index 0000000..0d68f17 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/getting_started/setup.txt @@ -0,0 +1,234 @@ +====== Automated Setup ====== + +The AI-Homelab uses two automated scripts for deployment. This is the recommended approach for most users. + +===== Quick Setup Commands ===== + +```bash +# 1. Clone the repository +git clone https://github.com/kelinfoxy/AI-Homelab.git +cd AI-Homelab + +# 2. Configure environment +cp .env.example .env +nano .env # Edit with your domain and tokens + +# 3. Run setup script +sudo ./scripts/setup-homelab.sh + +# 4. Run deployment script +sudo ./scripts/deploy-homelab.sh +``` + +That's it! Your homelab will be ready in 10-15 minutes. + +===== Detailed Setup Process ===== + +==== Step 1: Clone Repository ==== + +```bash +# Clone to your home directory +cd ~ +git clone https://github.com/kelinfoxy/AI-Homelab.git +cd AI-Homelab +``` + +**What this provides:** + * Complete homelab configuration + * Docker compose files for all services + * Automated deployment scripts + * Configuration templates + * Documentation and guides + +==== Step 2: Configure Environment ==== + +```bash +# Copy example configuration +cp .env.example .env + +# Edit with your settings +nano .env +``` + +**Required variables:** +``` +DOMAIN=yourdomain.duckdns.org +DUCKDNS_TOKEN=your-duckdns-token +ACME_EMAIL=your-email@example.com +``` + +**Optional variables:** +``` +SURFSHARK_USERNAME=your-vpn-username +SURFSHARK_PASSWORD=your-vpn-password +TZ=America/New_York +PUID=1000 +PGID=1000 +``` + +==== Step 3: Run Setup Script ==== + +```bash +# Execute with sudo privileges +sudo ./scripts/setup-homelab.sh +``` + +**What the setup script does:** + +**System Preparation:** + * Updates system packages + * Installs required dependencies (git, curl, etc.) + * Installs Docker Engine + Compose V2 + * Configures user permissions + * Sets up UFW firewall + * Enables SSH server + +**Authelia Configuration:** + * Generates cryptographic secrets (JWT, session, encryption keys) + * Prompts for admin username (default: admin) + * Prompts for secure password with confirmation + * Generates argon2id password hash + * Creates user database + +**Infrastructure Setup:** + * Creates `/opt/stacks/` directory structure + * Sets up Docker networks (traefik-network, homelab-network, etc.) + * Detects NVIDIA GPU and offers driver installation + +**Security Features:** + * Idempotent (safe to re-run) + * Comprehensive error handling + * Timeout protection for operations + * Clear troubleshooting messages + +==== Step 4: Run Deployment Script ==== + +```bash +# Deploy all services +sudo ./scripts/deploy-homelab.sh +``` + +**What the deployment script does:** + +**Prerequisites Check:** + * Validates environment configuration + * Verifies Docker installation + * Checks network connectivity + +**Core Stack Deployment:** + * Deploys DuckDNS, Traefik, Authelia, Gluetun + * Obtains wildcard SSL certificate (*.yourdomain.duckdns.org) + * Configures reverse proxy routing + +**Infrastructure Deployment:** + * Deploys Dockge, Pi-hole, monitoring tools + * Sets up dashboards (Homepage, Homarr) + * Configures service discovery + +**Health Checks:** + * Waits for services to become healthy + * Validates SSL certificate generation + * Opens Dockge in browser + +===== Post-Setup Configuration ===== + +==== Access Your Services ==== + +After deployment, access services at: + +| Service | URL | Status | +|---------|-----|--------| +| **Dockge** | `https://dockge.yourdomain.duckdns.org` | ✅ Primary management | +| **Homepage** | `https://home.yourdomain.duckdns.org` | ✅ Service dashboard | +| **Authelia** | `https://auth.yourdomain.duckdns.org` | ✅ SSO login | +| **Traefik** | `https://traefik.yourdomain.duckdns.org` | ✅ Proxy dashboard | + +**Default Credentials:** + * Username: `admin` (or your custom username) + * Password: The secure password you created + +==== Configure Two-Factor Authentication ==== + +1. Visit `https://auth.yourdomain.duckdns.org` +2. Log in with your admin credentials +3. Go to Settings → One-Time Password +4. Scan QR code with authenticator app +5. Enter verification code to enable 2FA + +==== Customize Homepage Dashboard ==== + +1. Visit `https://home.yourdomain.duckdns.org` +2. Click the settings icon (gear) +3. Configure services and widgets +4. Add API keys for enhanced widgets + +===== Troubleshooting Setup ===== + +==== Common Issues ==== + +**"Permission denied" when running scripts:** +```bash +# Ensure you're using sudo +sudo ./scripts/setup-homelab.sh + +# Check if scripts are executable +ls -la scripts/ +chmod +x scripts/*.sh +``` + +**Docker installation fails:** +```bash +# Remove conflicting packages +sudo apt remove docker docker-engine docker.io containerd runc + +# Re-run setup script +sudo ./scripts/setup-homelab.sh +``` + +**SSL certificate generation fails:** + * Check DuckDNS token is correct in `.env` + * Verify ports 80/443 are forwarded + * Wait 2-5 minutes for DNS propagation + * Check Traefik logs: `docker logs traefik` + +**Services not accessible:** + * Verify domain resolves: `nslookup yourdomain.duckdns.org` + * Check firewall: `sudo ufw status` + * View service logs: `docker compose -f /opt/stacks/core/docker-compose.yml logs` + +==== NVIDIA GPU Setup ==== + +If you have an NVIDIA GPU and want hardware acceleration: + +```bash +# During setup script, answer 'y' when prompted +# Or install manually after setup: + +# Add NVIDIA package repository +distribution=$(. /etc/os-release;echo $ID$VERSION_ID) +curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - +curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list + +# Install NVIDIA Docker +sudo apt-get update && sudo apt-get install -y nvidia-docker2 +sudo systemctl restart docker + +# Test GPU access +docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi +``` + +==== Manual Setup Alternative ==== + +If automated scripts fail, see [[getting_started:manual|Manual Setup Guide]] for step-by-step instructions. + +===== Next Steps ===== + +1. **Explore Services**: Use Dockge to deploy additional services +2. **Configure Backups**: Set up Backrest for automated backups +3. **Add Monitoring**: Deploy Grafana/Prometheus for observability +4. **Customize**: Modify services to fit your needs +5. **Contribute**: Help improve the project + +**Ready to deploy?** Run the setup script and enjoy your new homelab! + +**Need help?** Check [[troubleshooting:deployment|Deployment Troubleshooting]] or ask in [[https://github.com/kelinfoxy/AI-Homelab/discussions|GitHub Discussions]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/getting_started/start.txt b/config-templates/dokuwiki/data/pages/getting_started/start.txt new file mode 100644 index 0000000..287c9d1 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/getting_started/start.txt @@ -0,0 +1,126 @@ +====== Getting Started ====== + +Welcome to your AI-powered homelab! This guide will walk you through setting up your production-ready infrastructure with Dockge, Traefik, Authelia, and 70+ services. + +===== Quick Start Checklist ===== + +**Prerequisites:** + * [ ] Fresh Debian/Ubuntu server (or existing system) + * [ ] Root/sudo access + * [ ] Internet connection + * [ ] VS Code with GitHub Copilot (recommended) + +**Setup Process:** + * [ ] Clone repository: `git clone https://github.com/kelinfoxy/AI-Homelab.git` + * [ ] Configure `.env` file with your domain and tokens + * [ ] Run setup script: `sudo ./scripts/setup-homelab.sh` + * [ ] Run deployment script: `sudo ./scripts/deploy-homelab.sh` + * [ ] Access Dockge at `https://dockge.yourdomain.duckdns.org` + +**Post-Setup:** + * [ ] Set up 2FA with Authelia + * [ ] Configure Homepage dashboard + * [ ] Deploy additional services as needed + * [ ] Set up backups with Backrest + +===== What You Get ===== + +Your homelab includes: + +**Core Infrastructure (Deployed First):** + * **DuckDNS**: Dynamic DNS with Let's Encrypt wildcard SSL certificates + * **Traefik**: Reverse proxy with automatic HTTPS termination + * **Authelia**: SSO authentication protecting all services + * **Gluetun**: VPN client for secure downloads + * **Sablier**: Lazy loading service for resource management + +**Management Tools:** + * **Dockge**: Web-based Docker stack manager (PRIMARY interface) + * **Pi-hole**: Network-wide ad blocking and DNS + * **Dozzle**: Live Docker log viewer + * **Glances**: System monitoring dashboard + +**Dashboards:** + * **Homepage**: AI-configured service dashboard + * **Homarr**: Modern alternative dashboard + +**70+ Available Services:** + * Media: Plex, Jellyfin, Sonarr, Radarr, qBittorrent + * Productivity: Nextcloud, Gitea, BookStack, WordPress + * Home Automation: Home Assistant, Node-RED, Zigbee2MQTT + * Monitoring: Grafana, Prometheus, Uptime Kuma + * Development: VS Code Server, GitLab, Jupyter + * And many more... + +===== Architecture Overview ===== + +``` +Internet → DuckDNS → Traefik → Authelia → Services + ↓ + Wildcard SSL (*.yourdomain.duckdns.org) +``` + +**Key Features:** + * **File-based configuration**: AI-manageable YAML files + * **Automatic HTTPS**: Let's Encrypt wildcard certificates + * **SSO protection**: Authelia secures admin interfaces + * **VPN routing**: Downloads protected through Gluetun + * **Resource management**: Automatic container limits + * **Lazy loading**: Services start on-demand + +===== Access Your Services ===== + +After deployment, access services at: + +| Service | URL | Purpose | +|---------|-----|---------| +| **Dockge** | `https://dockge.yourdomain.duckdns.org` | Stack management | +| **Homepage** | `https://home.yourdomain.duckdns.org` | Service dashboard | +| **Authelia** | `https://auth.yourdomain.duckdns.org` | SSO login | +| **Traefik** | `https://traefik.yourdomain.duckdns.org` | Reverse proxy dashboard | +| **Pi-hole** | `http://pihole.yourdomain.duckdns.org` | DNS admin | +| **Dozzle** | `https://dozzle.yourdomain.duckdns.org` | Log viewer | + +**Default Credentials:** + * Username: `admin` (or custom username from setup) + * Password: Secure password created during setup + +===== Next Steps ===== + +1. **Complete Security Setup** + * Configure 2FA in Authelia + * Review service access policies + * Set up backup encryption + +2. **Deploy Core Services** + * Use Dockge to deploy media services + * Configure Homepage widgets + * Set up monitoring dashboards + +3. **Customize Your Stack** + * Add external service proxying + * Configure backup schedules + * Set up development environment + +4. **Learn Advanced Features** + * Use AI Copilot for management + * Explore service customization + * Contribute to the project + +===== Getting Help ===== + +**Documentation:** + * [[architecture:overview|Architecture Guide]] + * [[services:start|Service Reference]] + * [[troubleshooting:start|Troubleshooting]] + * [[reference:start|Quick Reference]] + +**Community:** + * [[https://github.com/kelinfoxy/AI-Homelab/issues|GitHub Issues]] + * [[https://github.com/kelinfoxy/AI-Homelab/discussions|Discussions]] + +**AI Assistance:** + * Use GitHub Copilot in VS Code + * Reference the [[development:copilot|Copilot Instructions]] + +Ready to get started? Continue to [[getting_started:prerequisites|Prerequisites]] or jump straight to [[getting_started:setup|Automated Setup]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/core/authelia.txt b/config-templates/dokuwiki/data/pages/services/core/authelia.txt new file mode 100644 index 0000000..011e7eb --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/core/authelia.txt @@ -0,0 +1,420 @@ +====== Authelia ====== + +Authelia is an open-source authentication and authorization server providing two-factor authentication and single sign-on (SSO) capabilities to secure access to your homelab services. + +===== Overview ===== + +**Purpose:** SSO authentication server +**URL:** `https://auth.yourdomain.duckdns.org` +**Authentication:** Direct login (username/password + 2FA) +**Deployment:** Automatic (core stack) +**Storage:** File-based user database + +===== Key Features ===== + +**Authentication Methods:** + * **Username/Password**: Secure credential verification + * **TOTP (Time-based One-Time Password)**: RFC 6238 compliant + * **WebAuthn**: Hardware security key support + * **Push Notifications**: Mobile authentication + +**Authorization:** + * **Domain-based policies**: Per-service access control + * **Group membership**: Role-based permissions + * **Bypass rules**: Direct access for media services + * **Session management**: Secure token handling + +**Security:** + * **Argon2id hashing**: Memory-hard password hashing + * **JWT tokens**: Secure session management + * **CSRF protection**: Cross-site request forgery prevention + * **Brute force protection**: Rate limiting and account lockout + +**Integration:** + * **Traefik middleware**: Reverse proxy authentication + * **LDAP support**: External user directory integration + * **SAML/OIDC**: Enterprise federation protocols + * **API access**: RESTful authentication API + +===== Configuration ===== + +**Main Configuration (configuration.yml):** +```yaml +--- +# Authelia configuration +host: 0.0.0.0 +port: 9091 + +log: + level: info + format: json + +jwt_secret: ${AUTHELIA_JWT_SECRET} +session: + name: authelia_session + secret: ${AUTHELIA_SESSION_SECRET} + expiration: 3600 # 1 hour + inactivity: 300 # 5 minutes + domain: yourdomain.duckdns.org + +storage: + encryption_key: ${AUTHELIA_STORAGE_ENCRYPTION_KEY} + local: + path: /config/db.sqlite3 + +access_control: + default_policy: deny + rules: + # Admin services require 2FA + - domain: "*.yourdomain.duckdns.org" + policy: two_factor + subject: + - "group:admins" + + # Media services bypass SSO + - domain: "jellyfin.yourdomain.duckdns.org" + policy: bypass + - domain: "plex.yourdomain.duckdns.org" + policy: bypass + +api: + disable_bearer_token: false + +authentication_backend: + file: + path: /config/users_database.yml + +notifier: + filesystem: + filename: /config/notification.txt +``` + +**User Database (users_database.yml):** +```yaml +--- +users: + admin: + displayname: Administrator + password: $argon2id$... + email: admin@yourdomain.duckdns.org + groups: + - admins + - dev +``` + +===== Docker Compose ===== + +```yaml +services: + authelia: + image: authelia/authelia:latest + container_name: authelia + restart: unless-stopped + networks: + - traefik-network + volumes: + - ./authelia/configuration.yml:/config/configuration.yml:ro + - ./authelia/users_database.yml:/config/users_database.yml + - ./authelia/db.sqlite3:/config/db.sqlite3 + - ./authelia/notification.txt:/config/notification.txt + environment: + - AUTHELIA_JWT_SECRET=${AUTHELIA_JWT_SECRET} + - AUTHELIA_SESSION_SECRET=${AUTHELIA_SESSION_SECRET} + - AUTHELIA_STORAGE_ENCRYPTION_KEY=${AUTHELIA_STORAGE_ENCRYPTION_KEY} + labels: + - "traefik.enable=true" + - "traefik.http.routers.authelia.rule=Host(`auth.${DOMAIN}`)" + - "traefik.http.routers.authelia.entrypoints=websecure" + - "traefik.http.routers.authelia.tls.certresolver=letsencrypt" + # No Authelia middleware for itself + - "traefik.http.services.authelia.loadbalancer.server.port=9091" + depends_on: + - authelia-redis # If using Redis + deploy: + resources: + limits: + cpus: '0.5' + memory: 256M + reservations: + cpus: '0.1' + memory: 64M +``` + +===== User Management ===== + +**Adding Users:** +```yaml +users: + newuser: + displayname: "New User" + password: "$argon2id$..." # Generate with authelia crypto hash generate argon2 + email: newuser@example.com + groups: + - users +``` + +**Password Hashing:** +```bash +# Generate Argon2id hash +docker run authelia/authelia:latest authelia crypto hash generate argon2 --password 'mypassword' +``` + +**Group Management:** +```yaml +# Define groups +groups: + admins: + - admin + users: + - user1 + - user2 + media: + - family +``` + +===== Access Control Policies ===== + +**Policy Types:** + * **deny**: Block all access + * **one_factor**: Username + password only + * **two_factor**: Username + password + 2FA + * **bypass**: No authentication required + +**Rule Structure:** +```yaml +rules: + - domain: "*.yourdomain.duckdns.org" + policy: two_factor + subject: + - "user:admin" + - "group:admins" + resources: + - "^/api/.*" # API endpoints +``` + +**Advanced Rules:** +```yaml +# Time-based access +- domain: "*.yourdomain.duckdns.org" + policy: two_factor + subject: "group:admins" + rules: + - operator: present + operand: http_request.header.Authorization + +# IP-based restrictions +- domain: "admin.yourdomain.duckdns.org" + policy: deny + networks: + - "192.168.1.0/24" # Allow only local network +``` + +===== Two-Factor Authentication ===== + +**TOTP Setup:** + 1. Access Authelia dashboard + 2. Go to **Settings** → **One-Time Password** + 3. Install authenticator app (Google Authenticator, Authy, etc.) + 4. Scan QR code or enter secret manually + 5. Enter verification code to enable + +**WebAuthn (Hardware Keys):** + * **Supported**: YubiKey, Google Titan, etc. + * **Protocol**: FIDO2/WebAuthn + * **Benefits**: Phishing-resistant, no shared secrets + +**Backup Codes:** + * Generate one-time use codes + * Store securely (encrypted password manager) + * Use only for emergency access + +===== Integration with Traefik ===== + +**ForwardAuth Middleware:** +```yaml +# In Traefik dynamic configuration +middlewares: + authelia: + forwardAuth: + address: "http://authelia:9091/api/verify?rd=https://auth.yourdomain.duckdns.org/" + trustForwardHeader: true + authResponseHeaders: + - "Remote-User" + - "Remote-Groups" + - "Remote-Name" + - "Remote-Email" +``` + +**Service Protection:** +```yaml +# Add to service labels +labels: + - "traefik.http.routers.service.middlewares=authelia@docker" +``` + +**Bypass Configuration:** +```yaml +# In Authelia configuration.yml +access_control: + rules: + - domain: "jellyfin.yourdomain.duckdns.org" + policy: bypass + - domain: "plex.yourdomain.duckdns.org" + policy: bypass +``` + +===== Session Management ===== + +**Session Configuration:** +```yaml +session: + name: authelia_session + secret: ${AUTHELIA_SESSION_SECRET} + expiration: 3600 # 1 hour + inactivity: 300 # 5 minutes + domain: yourdomain.duckdns.org + same_site: lax + secure: true + http_only: true +``` + +**Session Security:** + * **Secure cookies**: HTTPS only + * **HttpOnly**: JavaScript protection + * **SameSite**: CSRF protection + * **Expiration**: Automatic logout + +===== Monitoring & Logging ===== + +**Log Configuration:** +```yaml +log: + level: info # debug, info, warn, error + format: json # json or text + file: /config/authelia.log +``` + +**Monitoring Integration:** + * **Prometheus metrics**: `/metrics` endpoint + * **Health checks**: `/api/health` endpoint + * **Log aggregation**: Loki integration + * **Alerting**: Failed authentication notifications + +**Audit Logging:** + * **Authentication events**: Login/logout tracking + * **Authorization decisions**: Access control logging + * **Security events**: Failed attempts, lockouts + * **Compliance**: Audit trail for security reviews + +===== Security Best Practices ===== + +**Password Policies:** + * **Complexity**: Minimum 12 characters, mixed case, numbers, symbols + * **Expiration**: Regular rotation (90-180 days) + * **History**: Prevent password reuse + * **Lockout**: Account lockout after failed attempts + +**Session Security:** + * **Short sessions**: 1 hour maximum + * **Inactivity timeout**: 5-15 minutes + * **Secure cookies**: All security flags enabled + * **Token rotation**: Regular token refresh + +**Network Security:** + * **HTTPS only**: No HTTP access + * **HSTS**: HTTP Strict Transport Security + * **CSP**: Content Security Policy + * **Rate limiting**: Brute force protection + +===== Troubleshooting ===== + +**Login Issues:** +```bash +# Check Authelia logs +docker logs authelia + +# Verify configuration +docker exec authelia authelia validate-config /config/configuration.yml + +# Test authentication API +curl -k https://auth.yourdomain.duckdns.org/api/state +``` + +**2FA Problems:** + * Check system time synchronization + * Verify TOTP secret/code + * Clear browser cache + * Try different authenticator app + +**Middleware Issues:** +```bash +# Check Traefik logs +docker logs traefik | grep authelia + +# Test middleware +curl -H "Host: service.yourdomain.duckdns.org" http://localhost/ +``` + +**Configuration Errors:** + * Validate YAML syntax + * Check file permissions + * Verify environment variables + * Test configuration with `authelia validate-config` + +===== Advanced Features ===== + +**LDAP Integration:** +```yaml +authentication_backend: + ldap: + url: ldap://127.0.0.1 + base_dn: dc=example,dc=com + username_attribute: uid + additional_users_dn: ou=users + users_filter: (&({username_attribute}={input})(objectClass=person)) + groups_filter: (&(member={dn})(objectClass=groupOfNames)) + group_name_attribute: cn + mail_attribute: mail + display_name_attribute: displayName +``` + +**SAML/OIDC Identity Providers:** +```yaml +identity_providers: + oidc: + # OIDC configuration + saml: + # SAML configuration +``` + +**Custom Themes:** +```yaml +theme: dark # light, dark, grey, auto +``` + +**API Integration:** + * **REST API**: Programmatic authentication + * **Webhooks**: Event notifications + * **SCIM**: User provisioning + * **GraphQL**: Advanced queries + +===== Backup & Recovery ===== + +**Configuration Backup:** + * **Files**: `configuration.yml`, `users_database.yml` + * **Database**: `db.sqlite3` + * **Secrets**: Environment variables + +**Password Recovery:** + * **Backup codes**: One-time use recovery + * **Admin reset**: Administrative password reset + * **Self-service**: Password reset via email + +**Disaster Recovery:** + * **Configuration restore**: YAML file recovery + * **Database recovery**: SQLite backup restoration + * **Secret rotation**: Emergency credential management + +Authelia provides enterprise-grade authentication and authorization for your homelab, ensuring secure access to all your services. + +**Next:** Learn about [[services:core:duckdns|DuckDNS]] or [[services:core:gluetun|Gluetun]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/core/duckdns.txt b/config-templates/dokuwiki/data/pages/services/core/duckdns.txt new file mode 100644 index 0000000..723863a --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/core/duckdns.txt @@ -0,0 +1,289 @@ +====== DuckDNS ====== + +DuckDNS is a free dynamic DNS service that automatically updates your domain's IP address. In the AI-Homelab, DuckDNS provides the domain name that Traefik uses for SSL certificates and service routing. + +===== Overview ===== + +**Purpose:** Dynamic DNS service +**URL:** https://duckdns.org (external service) +**Authentication:** Token-based +**Deployment:** Automatic (core stack) +**Update Interval:** Every 5 minutes + +===== Key Features ===== + +**Dynamic DNS:** + * **Free service**: No cost for basic usage + * **Multiple domains**: Support for multiple subdomains + * **API integration**: RESTful API for updates + * **IPv4/IPv6**: Support for both IP versions + +**SSL Integration:** + * **Wildcard certificates**: *.yourdomain.duckdns.org + * **Let's Encrypt**: Automatic certificate generation + * **DNS challenge**: Domain ownership verification + * **Certificate renewal**: Automatic 90-day renewal + +**Reliability:** + * **High uptime**: 99.9%+ availability + * **Global CDN**: Fast DNS resolution worldwide + * **Redundant servers**: Multiple DNS servers + * **Monitoring**: Service status monitoring + +===== Configuration ===== + +**DuckDNS Account Setup:** + 1. Visit https://duckdns.org + 2. Create free account + 3. Choose domain name (your subdomain) + 4. Get API token from account settings + +**Environment Variables:** +```bash +# Required +DOMAIN=yourdomain.duckdns.org +DUCKDNS_TOKEN=your-api-token + +# Optional +DUCKDNS_SUBDOMAINS=subdomain1,subdomain2 +``` + +**Container Configuration:** +```yaml +services: + duckdns: + image: lscr.io/linuxserver/duckdns:latest + container_name: duckdns + restart: unless-stopped + environment: + - PUID=1000 + - PGID=1000 + - TZ=${TZ} + - SUBDOMAINS=${DUCKDNS_SUBDOMAINS:-yourdomain} + - TOKEN=${DUCKDNS_TOKEN} + deploy: + resources: + limits: + cpus: '0.1' + memory: 64M + reservations: + cpus: '0.01' + memory: 16M +``` + +===== How It Works ===== + +**DNS Update Process:** + 1. **IP Detection**: Container detects current public IP + 2. **API Call**: Sends update request to DuckDNS API + 3. **DNS Update**: DuckDNS updates DNS records + 4. **Propagation**: DNS changes propagate globally + 5. **Verification**: Container verifies update success + +**Update Frequency:** + * **Interval**: Every 5 minutes + * **Trigger**: Container startup + periodic updates + * **Condition**: IP address change detected + * **Logging**: Update success/failure logging + +**API Integration:** +```bash +# Manual update (for testing) +curl "https://www.duckdns.org/update?domains=yourdomain&token=your-token&ip=" + +# Check current IP +curl "https://www.duckdns.org/update?domains=yourdomain&token=your-token&verbose=1" +``` + +===== SSL Certificate Integration ===== + +**Traefik Configuration:** +```yaml +certificatesResolvers: + letsencrypt: + acme: + email: your-email@example.com + storage: /acme.json + dnsChallenge: + provider: duckdns + delayBeforeCheck: 30 +``` + +**Certificate Generation:** + * **Challenge Type**: DNS-01 + * **Record**: `_acme-challenge.yourdomain.duckdns.org` + * **Value**: Generated by Let's Encrypt + * **TTL**: 60 seconds (temporary) + +**Wildcard Certificate:** + * **Domain**: `*.yourdomain.duckdns.org` + * **Coverage**: All subdomains automatically + * **Type**: ECDSA P-256 + * **Validity**: 90 days + * **Renewal**: Automatic (30 days before expiry) + +===== Monitoring & Troubleshooting ===== + +**Container Logs:** +```bash +# View DuckDNS logs +docker logs duckdns + +# Follow logs in real-time +docker logs -f duckdns +``` + +**DNS Verification:** +```bash +# Check DNS resolution +nslookup yourdomain.duckdns.org + +# Check TXT record (during certificate generation) +dig TXT _acme-challenge.yourdomain.duckdns.org + +# Verify IP address +curl -s https://api.ipify.org +``` + +**Common Issues:** + +**DNS Not Updating:** +```bash +# Check token validity +curl "https://www.duckdns.org/update?domains=yourdomain&token=wrong-token" + +# Verify internet connectivity +ping -c 4 8.8.8.8 + +# Check container status +docker ps | grep duckdns +``` + +**SSL Certificate Issues:** + * **Rate Limiting**: Let's Encrypt limits (20 certificates/week) + * **DNS Propagation**: Wait 5-10 minutes after DNS update + * **Token Issues**: Verify DuckDNS token is correct + * **Port Forwarding**: Ensure 80/443 are forwarded + +**Troubleshooting Steps:** + 1. **Check logs**: `docker logs duckdns` + 2. **Verify token**: Test API manually + 3. **Check IP**: Confirm current public IP + 4. **Test DNS**: Verify domain resolution + 5. **Restart container**: `docker restart duckdns` + +===== Advanced Configuration ===== + +**Multiple Subdomains:** +```bash +# Environment variable +DUCKDNS_SUBDOMAINS=sub1,sub2,sub3 + +# Or in compose +environment: + - SUBDOMAINS=sub1,sub2,sub3 +``` + +**IPv6 Support:** +```bash +# Enable IPv6 updates +environment: + - IPV6=1 +``` + +**Custom Update Interval:** +```bash +# Modify container command +command: sh -c "while true; do /app/duckdns.sh; sleep 300; done" +# 300 seconds = 5 minutes (default) +``` + +===== Security Considerations ===== + +**Token Security:** + * **Storage**: Environment variables (not in code) + * **Access**: Limited to DuckDNS container only + * **Rotation**: Regular token renewal + * **Monitoring**: API usage monitoring + +**DNS Security:** + * **DNSSEC**: Not supported by DuckDNS + * **Rate Limiting**: API call restrictions + * **Monitoring**: DNS query logging + * **Backup**: Secondary DNS provider consideration + +===== Performance & Reliability ===== + +**Update Efficiency:** + * **Conditional Updates**: Only when IP changes + * **Fast API**: Quick response times + * **Error Handling**: Retry logic for failures + * **Logging**: Comprehensive update logging + +**Global Distribution:** + * **Anycast**: Multiple global DNS servers + * **CDN**: Fast resolution worldwide + * **Caching**: DNS record caching + * **Redundancy**: Multiple server locations + +===== Alternative DNS Providers ===== + +**If DuckDNS is insufficient:** + +**Cloudflare:** + * **Free tier**: 100,000 DNS queries/month + * **API**: Full DNS management + * **DNSSEC**: Supported + * **Analytics**: Query statistics + +**No-IP:** + * **Free tier**: 30-day renewal requirement + * **Multiple hosts**: Up to 3 free domains + * **Client software**: Windows/Mac/Linux clients + * **Groups**: Domain grouping + +**Dynu:** + * **Free tier**: 1 domain, 30-day renewal + * **API**: RESTful API + * **IPv6**: Supported + * **Analytics**: Basic statistics + +===== Migration Guide ===== + +**Switching DNS Providers:** + 1. **Register**: Create account with new provider + 2. **Configure**: Set up domain and get API token + 3. **Update**: Modify environment variables + 4. **Test**: Verify DNS resolution + 5. **SSL**: Update Traefik certificate resolver + 6. **Cleanup**: Remove old DuckDNS container + +**Certificate Migration:** + * **Backup**: Save acme.json file + * **Update**: Change DNS provider in Traefik + * **Renew**: Force certificate renewal + * **Verify**: Test SSL certificate validity + +===== Best Practices ===== + +**Domain Management:** + * **Choose wisely**: Select available, memorable domain + * **Documentation**: Record domain and token securely + * **Backup**: Include DNS settings in backup + * **Monitoring**: Monitor domain expiration + +**SSL Management:** + * **Wildcard**: Use for all subdomains + * **Backup**: Regular acme.json backups + * **Monitoring**: Certificate expiry alerts + * **Testing**: Regular SSL validation + +**Reliability:** + * **Redundancy**: Consider secondary DNS + * **Monitoring**: DNS and SSL health checks + * **Updates**: Keep container updated + * **Logging**: Monitor update success + +DuckDNS provides the foundation for your homelab's domain name and SSL certificates, ensuring secure and reliable access to all your services. + +**Next:** Learn about [[services:core:gluetun|Gluetun]] or explore [[architecture:networking|Network Architecture]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/core/gluetun.txt b/config-templates/dokuwiki/data/pages/services/core/gluetun.txt new file mode 100644 index 0000000..31ada15 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/core/gluetun.txt @@ -0,0 +1,404 @@ +====== Gluetun ====== + +Gluetun is a VPN client container that routes download services through VPN providers like Surfshark, NordVPN, or Mullvad. It provides network-level VPN protection for torrent clients and other download services. + +===== Overview ===== + +**Purpose:** VPN client for download services +**Supported VPNs:** Surfshark, NordVPN, Mullvad, ExpressVPN, ProtonVPN, and 20+ others +**Network Mode:** Service-based routing +**Deployment:** Core stack (always running) +**Resource Usage:** Low (minimal CPU/memory) + +===== Key Features ===== + +**VPN Providers:** + * **Surfshark**: Primary recommended provider + * **WireGuard/OpenVPN**: Multiple protocol support + * **Port Forwarding**: Automatic port forwarding + * **Kill Switch**: Network isolation when VPN fails + +**Network Routing:** + * **Service Mode**: `network_mode: "service:gluetun"` + * **Port Mapping**: VPN ports mapped to host + * **DNS**: VPN provider DNS servers + * **Firewall**: Built-in firewall rules + +**Security Features:** + * **IP Leak Protection**: Prevents IP exposure + * **DNS Leak Protection**: VPN DNS enforcement + * **Kill Switch**: Automatic connection blocking + * **Protocol Selection**: WireGuard/OpenVPN choice + +===== Configuration ===== + +**Environment Variables:** +```bash +# VPN Provider (Surfshark recommended) +VPN_SERVICE_PROVIDER=surfshark +VPN_TYPE=wireguard + +# Credentials +VPN_USERNAME=your-username +VPN_PASSWORD=your-password + +# Optional: Specific server/country +SERVER_COUNTRIES=Netherlands +SERVER_CITIES=Amsterdam + +# Optional: WireGuard specific +WIREGUARD_PRIVATE_KEY=your-private-key +WIREGUARD_ADDRESSES=10.0.0.0/8 +``` + +**Container Configuration:** +```yaml +services: + gluetun: + image: qmcgaw/gluetun:latest + container_name: gluetun + restart: unless-stopped + cap_add: + - NET_ADMIN + devices: + - /dev/net/tun:/dev/net/tun + environment: + - VPN_SERVICE_PROVIDER=${VPN_SERVICE_PROVIDER} + - VPN_TYPE=${VPN_TYPE} + - VPN_USERNAME=${VPN_USERNAME} + - VPN_PASSWORD=${VPN_PASSWORD} + - SERVER_COUNTRIES=${SERVER_COUNTRIES:-Netherlands} + volumes: + - ./gluetun/config:/config + ports: + - 8080:8080 # qBittorrent WebUI + - 6881:6881 # qBittorrent TCP + - 6881:6881/udp # qBittorrent UDP + networks: + - traefik-network + deploy: + resources: + limits: + cpus: '0.5' + memory: 256M + reservations: + cpus: '0.1' + memory: 64M +``` + +===== How VPN Routing Works ===== + +**Service-Based Routing:** +```yaml +# Download service configuration +services: + qbittorrent: + image: lscr.io/linuxserver/qbittorrent:latest + network_mode: "service:gluetun" # Routes through VPN + depends_on: + - gluetun + volumes: + - ./qbittorrent/config:/config + - /mnt/downloads:/downloads + environment: + - PUID=1000 + - PGID=1000 + - TZ=${TZ} + # No ports exposed - accessed via Gluetun +``` + +**Network Flow:** + 1. **Gluetun Container**: Establishes VPN connection + 2. **Service Mode**: Download service shares Gluetun's network stack + 3. **VPN Routing**: All traffic from download service goes through VPN + 4. **Port Mapping**: VPN ports mapped to Gluetun container ports + 5. **Access**: Services access download client via Gluetun's IP/port + +===== VPN Provider Setup ===== + +**Surfshark (Recommended):** + 1. **Sign up**: https://surfshark.com + 2. **Get credentials**: Username/password from account + 3. **WireGuard**: Generate private key (optional, faster) + 4. **Configure**: Use in environment variables + +**WireGuard Setup (Optional but Recommended):** +```bash +# Generate private key +wg genkey + +# Or use Surfshark app to get key +# Account -> Manual Setup -> WireGuard +``` + +**Other Providers:** +```yaml +# NordVPN +VPN_SERVICE_PROVIDER=nordvpn +VPN_TYPE=openvpn + +# Mullvad +VPN_SERVICE_PROVIDER=mullvad +VPN_TYPE=wireguard + +# ExpressVPN +VPN_SERVICE_PROVIDER=expressvpn +VPN_TYPE=openvpn +``` + +===== Port Management ===== + +**Port Forwarding:** +```yaml +# Gluetun ports (map download service ports) +ports: + - 8080:8080 # WebUI + - 6881:6881 # TCP torrent port + - 6881:6881/udp # UDP torrent port + - 51413:51413 # Alternative torrent port + - 51413:51413/udp +``` + +**Dynamic Port Forwarding:** + * **Automatic**: Some providers support automatic port forwarding + * **Manual**: Configure specific ports in VPN provider + * **Testing**: Verify port forwarding with online tools + +**Port Forwarding Check:** +```bash +# Check if port is open +curl -s "https://portchecker.co/check" --data "port=6881" + +# Or use online port checker +# Visit: https://www.yougetsignal.com/tools/open-ports/ +``` + +===== Monitoring & Troubleshooting ===== + +**Container Logs:** +```bash +# View Gluetun logs +docker logs gluetun + +# Follow logs in real-time +docker logs -f gluetun +``` + +**VPN Status Check:** +```bash +# Check VPN connection +docker exec gluetun sh -c "curl -s ifconfig.me" + +# Verify VPN IP (should be different from your real IP) +docker exec gluetun sh -c "curl -s https://api.ipify.org" +``` + +**Kill Switch Testing:** +```bash +# Test kill switch (disconnect VPN) +docker exec gluetun sh -c "iptables -P OUTPUT DROP" + +# Restore (reconnect VPN) +docker restart gluetun +``` + +**Common Issues:** + +**VPN Connection Failed:** +```bash +# Check credentials +docker logs gluetun | grep -i "auth\|login\|password" + +# Verify server selection +docker logs gluetun | grep -i "server\|country" + +# Test VPN provider status +# Visit provider status page +``` + +**DNS Leaks:** +```bash +# Check DNS servers +docker exec gluetun sh -c "cat /etc/resolv.conf" + +# Test DNS leak +# Visit: https://www.dnsleaktest.com +``` + +**Port Forwarding Issues:** + * **Provider Support**: Not all VPNs support port forwarding + * **Server Selection**: Choose servers that support port forwarding + * **Configuration**: Enable port forwarding in VPN account + * **Testing**: Use port checking tools + +**Troubleshooting Steps:** + 1. **Check logs**: `docker logs gluetun` + 2. **Verify credentials**: Test with VPN provider app + 3. **Test connection**: Manual VPN connection + 4. **Check ports**: Verify port forwarding + 5. **Restart**: `docker restart gluetun` + +===== Security Considerations ===== + +**Kill Switch Protection:** + * **Automatic**: Blocks all traffic if VPN disconnects + * **Testing**: Regularly test kill switch functionality + * **Monitoring**: Monitor VPN connection status + * **Alerts**: Set up notifications for VPN failures + +**IP Leak Prevention:** + * **WebRTC**: Disable WebRTC in browsers + * **IPv6**: Disable IPv6 if not needed + * **DNS**: Use VPN DNS servers only + * **Testing**: Regular leak testing + +**Credential Security:** + * **Storage**: Environment variables (not in code) + * **Access**: Limited to Gluetun container + * **Rotation**: Regular password changes + * **2FA**: Enable 2FA on VPN account + +===== Performance Optimization ===== + +**Protocol Selection:** + * **WireGuard**: Faster, more secure (recommended) + * **OpenVPN**: More compatible, slightly slower + * **IKEv2**: Mobile-optimized + +**Server Selection:** + * **Location**: Choose closest servers + * **Load**: Select less crowded servers + * **Features**: Port forwarding capable servers + * **Testing**: Test different server locations + +**Resource Limits:** +```yaml +deploy: + resources: + limits: + cpus: '0.5' # Low CPU usage + memory: 256M # Minimal memory + reservations: + cpus: '0.1' + memory: 64M +``` + +===== Advanced Configuration ===== + +**Custom VPN Configuration:** +```yaml +# Custom OpenVPN config +volumes: + - ./gluetun/config:/config + - ./custom-config:/custom + +environment: + - VPN_TYPE=openvpn + - OPENVPN_CUSTOM_CONFIG=/custom/my-config.ovpn +``` + +**Multiple VPN Services:** +```yaml +# Separate Gluetun instances for different services +services: + gluetun-us: + # US-based VPN + environment: + - SERVER_COUNTRIES=United States + + gluetun-nl: + # Netherlands-based VPN + environment: + - SERVER_COUNTRIES=Netherlands +``` + +**Health Checks:** +```yaml +healthcheck: + test: ["CMD", "curl", "-f", "https://api.ipify.org"] + interval: 30s + timeout: 10s + retries: 3 +``` + +===== Integration with Download Services ===== + +**qBittorrent Configuration:** +```yaml +# In qbittorrent config +# Network settings +Connection Limits: + Global max number of upload slots: 20 + Max number of upload slots per torrent: 5 + +# BitTorrent settings +Enable DHT: Yes +Enable PeX: Yes +Enable LSD: Yes + +# WebUI settings +IP Address: 0.0.0.0 +Port: 8080 +``` + +**Transmission Configuration:** +```yaml +# transmission-daemon settings.json +{ + "rpc-port": 9091, + "rpc-username": "admin", + "rpc-password": "password", + "rpc-whitelist-enabled": false, + "download-dir": "/downloads", + "incomplete-dir": "/downloads/incomplete" +} +``` + +===== Backup & Recovery ===== + +**Configuration Backup:** +```bash +# Backup Gluetun config +docker run --rm \ + -v gluetun-config:/config \ + -v $(pwd)/backup:/backup \ + busybox tar czf /backup/gluetun-config.tar.gz /config +``` + +**VPN Credential Rotation:** + 1. **Generate new credentials** in VPN provider + 2. **Update environment variables** in .env + 3. **Restart Gluetun**: `docker restart gluetun` + 4. **Verify connection**: Check logs and IP + 5. **Test downloads**: Verify torrent functionality + +===== Best Practices ===== + +**VPN Selection:** + * **Reliability**: Choose reputable providers + * **Speed**: Test connection speeds + * **Features**: Port forwarding, kill switch + * **Privacy**: No-logs policy + * **Cost**: Balance features vs price + +**Security:** + * **Kill Switch**: Always enabled + * **Regular Testing**: Monthly leak tests + * **Updates**: Keep Gluetun updated + * **Monitoring**: VPN status monitoring + +**Performance:** + * **WireGuard**: Prefer over OpenVPN + * **Server Location**: Closest available + * **Load Balancing**: Distribute across servers + * **Monitoring**: Track connection quality + +**Maintenance:** + * **Credential Rotation**: Regular password changes + * **Log Review**: Monitor connection logs + * **Update Checks**: Keep VPN client updated + * **Backup**: Regular configuration backups + +Gluetun provides essential VPN protection for download services, ensuring your torrenting and file sharing activities remain private and secure. + +**Next:** Learn about [[services:core:sablier|Sablier]] or explore [[architecture:security|Security Architecture]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/core/sablier.txt b/config-templates/dokuwiki/data/pages/services/core/sablier.txt new file mode 100644 index 0000000..2ae46a4 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/core/sablier.txt @@ -0,0 +1,401 @@ +====== Sablier ====== + +Sablier is a lazy loading service that starts Docker containers on-demand when accessed, then automatically stops them after a period of inactivity. This saves system resources by keeping unused services stopped until needed. + +===== Overview ===== + +**Purpose:** On-demand container startup +**Integration:** Traefik middleware +**Resource Savings:** Significant CPU/memory reduction +**Deployment:** Core stack (always running) +**Configuration:** Label-based activation + +===== Key Features ===== + +**Lazy Loading:** + * **On-Demand Startup**: Containers start when accessed + * **Automatic Shutdown**: Stop after inactivity timeout + * **Resource Efficiency**: Save CPU/memory when not used + * **Transparent**: No user experience changes + +**Integration:** + * **Traefik Middleware**: HTTP request triggering + * **Label Configuration**: Simple Docker labels + * **Group Management**: Related services as groups + * **Health Checks**: Wait for service readiness + +**Performance:** + * **Fast Startup**: Quick container initialization + * **Timeout Control**: Configurable inactivity periods + * **Queue Management**: Handle multiple concurrent requests + * **Monitoring**: Startup/shutdown tracking + +===== Configuration ===== + +**Container Configuration:** +```yaml +services: + sablier: + image: acouvreur/sablier:latest + container_name: sablier + restart: unless-stopped + environment: + - SABLIER_STRATEGY=docker-api + - SABLIER_DOCKER_API_VERSION=1.41 + - SABLIER_DOCKER_NETWORK=traefik-network + - SABLIER_TIMEOUT=5m + - SABLIER_SESSION_DURATION=168h + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + networks: + - traefik-network + deploy: + resources: + limits: + cpus: '0.2' + memory: 128M + reservations: + cpus: '0.05' + memory: 32M +``` + +**Service Integration Labels:** +```yaml +# Enable Sablier for a service +labels: + - "sablier.enable=true" + - "sablier.group=my-service-group" + - "sablier.start-on-demand=true" + - "sablier.timeout=5m" # Optional: per-service timeout +``` + +===== How Lazy Loading Works ===== + +**Request Flow:** + 1. **HTTP Request**: User accesses service URL + 2. **Traefik Routing**: Request hits Traefik with Sablier middleware + 3. **Sablier Check**: Sablier checks if target service is running + 4. **Container Start**: If stopped, Sablier starts the container + 5. **Health Wait**: Waits for service to be ready + 6. **Request Forward**: Forwards request to running service + 7. **Timeout Reset**: Resets inactivity timer + +**Automatic Shutdown:** + * **Inactivity Detection**: No requests for timeout period + * **Graceful Shutdown**: Container stopped cleanly + * **Resource Recovery**: CPU/memory freed up + * **Restart Ready**: Ready for next access + +===== Service Configuration ===== + +**Basic Setup:** +```yaml +services: + my-service: + image: my-service:latest + labels: + # Traefik labels (normal) + - "traefik.enable=true" + - "traefik.http.routers.my-service.rule=Host(`my-service.${DOMAIN}`)" + - "traefik.http.routers.my-service.entrypoints=websecure" + - "traefik.http.routers.my-service.tls.certresolver=letsencrypt" + - "traefik.http.routers.my-service.middlewares=authelia@docker" + + # Sablier labels (lazy loading) + - "sablier.enable=true" + - "sablier.group=my-service" + - "sablier.start-on-demand=true" +``` + +**Advanced Configuration:** +```yaml +labels: + # Custom timeout (overrides global) + - "sablier.timeout=10m" + + # Custom session duration + - "sablier.session-duration=24h" + + # Group multiple services + - "sablier.group=media-stack" +``` + +===== Timeout Management ===== + +**Global Timeout:** +```yaml +environment: + - SABLIER_TIMEOUT=5m # Default 5 minutes +``` + +**Per-Service Timeout:** +```yaml +labels: + - "sablier.timeout=15m" # Override for this service +``` + +**Session Duration:** +```yaml +environment: + - SABLIER_SESSION_DURATION=168h # 7 days default +``` + +**Timeout Behavior:** + * **Activity Reset**: Each request resets the timer + * **Graceful Shutdown**: Clean container stop + * **Resource Recovery**: Memory/CPU freed + * **Quick Restart**: Fast startup on next access + +===== Group Management ===== + +**Service Groups:** +```yaml +# Related services in same group +services: + sonarr: + labels: + - "sablier.group=media-management" + + radarr: + labels: + - "sablier.group=media-management" + + prowlarr: + labels: + - "sablier.group=media-management" +``` + +**Group Benefits:** + * **Coordinated Startup**: Start related services together + * **Shared Timeout**: Group timeout applies to all + * **Resource Management**: Better resource planning + * **Dependency Handling**: Handle service dependencies + +===== Monitoring & Troubleshooting ===== + +**Sablier Logs:** +```bash +# View Sablier logs +docker logs sablier + +# Follow logs in real-time +docker logs -f sablier +``` + +**Startup Monitoring:** +```bash +# Check service startup +docker logs sablier | grep "Starting container" + +# Monitor shutdowns +docker logs sablier | grep "Stopping container" +``` + +**Debug Mode:** +```yaml +environment: + - SABLIER_LOG_LEVEL=debug +``` + +**Common Issues:** + +**Service Not Starting:** +```bash +# Check Sablier logs +docker logs sablier | grep -i "error\|failed" + +# Verify Docker socket access +docker exec sablier ls -la /var/run/docker.sock + +# Check network connectivity +docker exec sablier ping -c 2 traefik +``` + +**Timeout Issues:** + * **Too Short**: Services stopping too quickly + * **Too Long**: Resources not freed timely + * **Per-Service**: Override global timeout + * **Testing**: Monitor actual usage patterns + +**Middleware Issues:** + * **Traefik Config**: Verify middleware order + * **Label Format**: Check label syntax + * **Network Access**: Ensure Sablier can reach Docker API + +**Troubleshooting Steps:** + 1. **Check logs**: `docker logs sablier` + 2. **Verify labels**: Check service configuration + 3. **Test startup**: Manual container start + 4. **Check network**: Verify Docker API access + 5. **Restart Sablier**: `docker restart sablier` + +===== Performance Optimization ===== + +**Resource Limits:** +```yaml +deploy: + resources: + limits: + cpus: '0.2' # Low CPU usage + memory: 128M # Minimal memory + reservations: + cpus: '0.05' + memory: 32M +``` + +**Timeout Tuning:** + * **Frequent Access**: Longer timeouts (15-30m) + * **Infrequent Access**: Shorter timeouts (2-5m) + * **Resource Intensive**: Consider manual management + * **User Patterns**: Monitor and adjust based on usage + +**Startup Optimization:** + * **Health Checks**: Fast health check endpoints + * **Dependencies**: Minimize startup dependencies + * **Caching**: Use persistent volumes for data + * **Pre-warming**: Keep critical services running + +===== Security Considerations ===== + +**Docker Socket Access:** + * **Read-Only**: Mount socket as read-only + * **Limited Access**: Only Sablier container access + * **Network Isolation**: Separate network for Sablier + * **Monitoring**: Monitor Docker API usage + +**Service Security:** + * **No Direct Access**: Services only accessible via Traefik + * **Authentication**: Authelia protection maintained + * **SSL**: HTTPS encryption preserved + * **Timeout Security**: Automatic cleanup prevents exposure + +===== Advanced Configuration ===== + +**Custom Strategies:** +```yaml +environment: + - SABLIER_STRATEGY=docker-api # Default + # Alternative: kubernetes, swarm +``` + +**Queue Management:** +```yaml +environment: + - SABLIER_QUEUE_SIZE=10 # Concurrent startups + - SABLIER_QUEUE_TIMEOUT=30s # Queue wait timeout +``` + +**Health Check Configuration:** +```yaml +environment: + - SABLIER_HEALTH_CHECK=true + - SABLIER_HEALTH_CHECK_TIMEOUT=30s + - SABLIER_HEALTH_CHECK_INTERVAL=5s +``` + +**Dynamic Configuration:** +```yaml +# Via environment variables +environment: + - SABLIER_SERVICES=my-service:5m,other-service:10m +``` + +===== Integration Examples ===== + +**Media Management Stack:** +```yaml +services: + sonarr: + labels: + - "sablier.enable=true" + - "sablier.group=media-mgmt" + - "sablier.timeout=15m" + + radarr: + labels: + - "sablier.enable=true" + - "sablier.group=media-mgmt" + - "sablier.timeout=15m" + + prowlarr: + labels: + - "sablier.enable=true" + - "sablier.group=media-mgmt" + - "sablier.timeout=10m" +``` + +**Development Tools:** +```yaml +services: + code-server: + labels: + - "sablier.enable=true" + - "sablier.group=dev-tools" + - "sablier.timeout=2h" # Longer for development + + jupyter: + labels: + - "sablier.enable=true" + - "sablier.group=dev-tools" + - "sablier.timeout=1h" +``` + +===== Best Practices ===== + +**Service Selection:** + * **Infrequently Used**: Perfect for rarely accessed services + * **Resource Intensive**: Save resources on heavy services + * **Development Tools**: Good for dev environments + * **Always-On**: Keep critical services running + +**Timeout Configuration:** + * **Monitor Usage**: Track actual access patterns + * **Adjust Gradually**: Start conservative, adjust based on logs + * **Per-Service**: Different timeouts for different services + * **User Feedback**: Consider user experience + +**Resource Management:** + * **Capacity Planning**: Calculate resource savings + * **Monitoring**: Track startup/shutdown patterns + * **Optimization**: Tune based on system resources + * **Backup Plan**: Manual startup if needed + +**Maintenance:** + * **Log Review**: Regular log analysis + * **Performance Monitoring**: Track resource usage + * **Configuration Updates**: Update timeouts as needed + * **Documentation**: Document lazy-loaded services + +===== Monitoring & Alerts ===== + +**Log Analysis:** +```bash +# Startup events +docker logs sablier | grep "Starting" + +# Shutdown events +docker logs sablier | grep "Stopping" + +# Errors +docker logs sablier | grep -i "error" +``` + +**Performance Metrics:** + * **Startup Time**: Time to service readiness + * **Resource Usage**: CPU/memory before/after + * **Access Patterns**: Frequency of service access + * **Timeout Effectiveness**: Actual vs configured timeouts + +**Health Monitoring:** +```yaml +# Add health check +healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:10000/health"] + interval: 30s + timeout: 10s + retries: 3 +``` + +Sablier significantly reduces resource usage by keeping unused services stopped until needed, while maintaining a seamless user experience through automatic on-demand startup. + +**Next:** Explore [[architecture:storage|Storage Architecture]] or return to [[services:start|Services Overview]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/core/traefik.txt b/config-templates/dokuwiki/data/pages/services/core/traefik.txt new file mode 100644 index 0000000..373e035 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/core/traefik.txt @@ -0,0 +1,366 @@ +====== Traefik ====== + +Traefik is a modern HTTP reverse proxy and load balancer that makes deploying microservices easy. In the AI-Homelab, Traefik serves as the main entry point for all services, providing automatic HTTPS, load balancing, and routing. + +===== Overview ===== + +**Purpose:** HTTP reverse proxy and load balancer +**URL:** `https://traefik.yourdomain.duckdns.org` +**Authentication:** Authelia SSO +**Deployment:** Automatic (core stack) +**Configuration:** File-based (YAML) + +===== Key Features ===== + +**Automatic HTTPS:** + * Let's Encrypt integration + * Wildcard SSL certificates + * Automatic renewal (90 days) + * A+ SSL rating + +**Service Discovery:** + * Docker label-based routing + * Dynamic configuration reloading + * Zero-downtime deployments + * Health check integration + +**Load Balancing:** + * Round-robin distribution + * Weighted load balancing + * Session stickiness + * Circuit breaker protection + +**Security:** + * HTTP security headers + * Rate limiting + * IP whitelisting + * CORS protection + +===== Configuration ===== + +**Static Configuration (traefik.yml):** +```yaml +global: + checkNewVersion: false + sendAnonymousUsage: false + +api: + dashboard: true + insecure: false + +entryPoints: + web: + address: ":80" + http: + redirections: + entryPoint: + to: websecure + scheme: https + websecure: + address: ":443" + http: + tls: + certResolver: letsencrypt + +providers: + docker: + endpoint: "unix:///var/run/docker.sock" + exposedByDefault: false + network: traefik-network + file: + directory: /dynamic + watch: true + +certificatesResolvers: + letsencrypt: + acme: + email: your-email@example.com + storage: /acme.json + dnsChallenge: + provider: duckdns + delayBeforeCheck: 30 +``` + +**Dynamic Configuration (external.yml):** +```yaml +http: + middlewares: + authelia: + forwardAuth: + address: "http://authelia:9091/api/verify?rd=https://auth.yourdomain.duckdns.org/" + trustForwardHeader: true + authResponseHeaders: + - "Remote-User" + - "Remote-Groups" + - "Remote-Name" + - "Remote-Email" + + security-headers: + headers: + customRequestHeaders: + X-Forwarded-Proto: "https" + customResponseHeaders: + X-Frame-Options: "SAMEORIGIN" + X-Content-Type-Options: "nosniff" + Referrer-Policy: "strict-origin-when-cross-origin" + Permissions-Policy: "geolocation=(), microphone=(), camera=()" + stsSeconds: 31536000 + stsIncludeSubdomains: true + stsPreload: true +``` + +===== Docker Compose ===== + +```yaml +services: + traefik: + image: traefik:v3.0 + container_name: traefik + restart: unless-stopped + networks: + - traefik-network + ports: + - "80:80" + - "443:443" + volumes: + - ./traefik.yml:/etc/traefik/traefik.yml:ro + - ./dynamic:/dynamic:ro + - ./acme.json:/acme.json + - /var/run/docker.sock:/var/run/docker.sock:ro + environment: + - DUCKDNS_TOKEN=${DUCKDNS_TOKEN} + labels: + - "traefik.enable=true" + - "traefik.http.routers.traefik.rule=Host(`traefik.${DOMAIN}`)" + - "traefik.http.routers.traefik.entrypoints=websecure" + - "traefik.http.routers.traefik.tls.certresolver=letsencrypt" + - "traefik.http.routers.traefik.middlewares=authelia@docker" + - "traefik.http.routers.traefik.service=api@internal" + - "traefik.http.services.traefik.loadbalancer.server.port=8080" + deploy: + resources: + limits: + cpus: '0.5' + memory: 256M + reservations: + cpus: '0.1' + memory: 64M +``` + +===== Service Routing ===== + +**Standard Service Labels:** +```yaml +labels: + - "traefik.enable=true" + - "traefik.http.routers.service.rule=Host(`service.${DOMAIN}`)" + - "traefik.http.routers.service.entrypoints=websecure" + - "traefik.http.routers.service.tls.certresolver=letsencrypt" + - "traefik.http.routers.service.middlewares=authelia@docker" + - "traefik.http.services.service.loadbalancer.server.port=8080" +``` + +**Router Components:** + * **Rule**: Host matching (e.g., `Host(`service.domain.org`)`) + * **EntryPoint**: HTTP/HTTPS endpoint + * **TLS**: Certificate resolver + * **Middlewares**: Authentication, security headers + * **Service**: Backend service definition + +**Advanced Routing:** +```yaml +# Path-based routing +- "traefik.http.routers.api.rule=Host(`api.${DOMAIN}`) && PathPrefix(`/v1`)" +- "traefik.http.routers.web.rule=Host(`app.${DOMAIN}`)" + +# Header-based routing +- "traefik.http.routers.mobile.rule=Host(`app.${DOMAIN}`) && Headers(`User-Agent`, `*Mobile*`)" + +# Priority routing +- "traefik.http.routers.specific.rule=Host(`service.${DOMAIN}`) && Path(`/api`)" +- "traefik.http.routers.specific.priority=100" +``` + +===== SSL Certificate Management ===== + +**Certificate Generation:** + * **Challenge**: DNS-01 (DuckDNS) + * **Provider**: Let's Encrypt + * **Type**: ECDSA P-256 + * **Validity**: 90 days + * **Renewal**: Automatic (30 days before expiry) + +**Certificate Storage:** + * **File**: `/opt/stacks/core/traefik/acme.json` + * **Permissions**: 600 (owner read/write only) + * **Backup**: Include in backup strategy + * **Format**: JSON with encrypted private keys + +**Troubleshooting SSL:** +```bash +# Check certificate status +echo | openssl s_client -connect yourdomain.duckdns.org:443 -servername service.yourdomain.duckdns.org 2>/dev/null | openssl x509 -noout -subject -dates + +# View Traefik logs +docker logs traefik | grep certificate + +# Check DNS TXT record +dig TXT _acme-challenge.yourdomain.duckdns.org +``` + +===== Monitoring & Logging ===== + +**Dashboard Access:** + * URL: `https://traefik.yourdomain.duckdns.org` + * Features: Real-time routing, health status, metrics + * Authentication: Authelia SSO required + +**Log Configuration:** +```yaml +log: + level: INFO + format: json + +accessLog: + filePath: /var/log/traefik/access.log + format: json + filters: + statusCodes: ["200-299", "400-499", "500-599"] +``` + +**Metrics Integration:** + * **Prometheus**: `/metrics` endpoint + * **Health Checks**: Service health monitoring + * **Performance**: Response time tracking + +===== Security Features ===== + +**Authentication Middleware:** + * **Authelia Integration**: SSO for protected services + * **Bypass Rules**: Direct access for media services + * **Session Management**: Secure cookie handling + +**Rate Limiting:** +```yaml +middlewares: + rate-limit: + rateLimit: + burst: 100 + average: 50 +``` + +**IP Whitelisting:** +```yaml +middlewares: + ip-whitelist: + ipWhiteList: + sourceRange: + - "192.168.1.0/24" + - "10.0.0.0/8" +``` + +===== Performance Optimization ===== + +**Caching:** +```yaml +middlewares: + cache: + inFlightReq: + amount: 64 +``` + +**Compression:** + * **Gzip**: Automatic text compression + * **Brotli**: Advanced compression (if supported) + +**Connection Pooling:** + * **Keep-Alive**: Persistent connections + * **Connection Reuse**: Reduced latency + * **Timeout Management**: Connection limits + +===== Troubleshooting ===== + +**Service Not Accessible:** +```bash +# Check if service is running +docker ps | grep service-name + +# Verify Traefik labels +docker inspect service-name | grep traefik + +# Check Traefik logs +docker logs traefik | grep service-name +``` + +**SSL Issues:** + * Verify DuckDNS token + * Check DNS propagation + * Confirm port forwarding + * Review certificate logs + +**Routing Problems:** + * Validate router rules + * Check middleware configuration + * Test service connectivity + * Review access logs + +**Performance Issues:** + * Monitor resource usage + * Check connection limits + * Review middleware stack + * Analyze access patterns + +===== External Service Proxying ===== + +**Proxying Non-Docker Services:** +```yaml +# In dynamic/external.yml +http: + routers: + external-service: + rule: "Host(`external.yourdomain.duckdns.org`)" + service: external-service + middlewares: + - authelia@docker + services: + external-service: + loadBalancer: + servers: + - url: "http://192.168.1.100:8123" +``` + +**Use Cases:** + * Raspberry Pi Home Assistant + * NAS devices + * Legacy applications + * Network printers + +===== Best Practices ===== + +**Configuration Management:** + * Use version control for config files + * Test changes in staging + * Document custom routing rules + * Regular backup of acme.json + +**Security:** + * Keep Traefik updated + * Monitor access logs + * Use strong authentication + * Regular security audits + +**Performance:** + * Implement appropriate caching + * Use connection pooling + * Monitor resource usage + * Optimize middleware stack + +**Monitoring:** + * Set up alerts for failures + * Monitor certificate expiry + * Track performance metrics + * Regular log analysis + +Traefik is the backbone of your homelab's networking infrastructure, providing secure, efficient, and reliable service routing. + +**Next:** Learn about [[services:core:authelia|Authelia]] or [[services:core:duckdns|DuckDNS]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/infrastructure/code-server.txt b/config-templates/dokuwiki/data/pages/services/infrastructure/code-server.txt new file mode 100644 index 0000000..ec9b8c1 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/infrastructure/code-server.txt @@ -0,0 +1,428 @@ +====== Code Server ====== + +Code Server is a web-based version of Visual Studio Code that runs in your browser, providing a full development environment accessible from anywhere. It includes all VS Code features, extensions, and integrates with your homelab development workflow. + +===== Overview ===== + +**Purpose:** Browser-based code editor +**URL:** https://code.yourdomain.duckdns.org +**Authentication:** Authelia SSO protected +**Deployment:** Infrastructure stack +**Interface:** Full VS Code web interface + +===== Key Features ===== + +**VS Code Features:** + * **Full IDE**: Complete Visual Studio Code experience + * **Extensions**: Access to VS Code marketplace + * **Themes**: All VS Code themes and customization + * **Git Integration**: Built-in Git version control + +**Web Access:** + * **Browser-based**: Access from any device + * **Responsive Design**: Works on desktop and mobile + * **Persistent Sessions**: Maintain work sessions + * **File Synchronization**: Sync across devices + +**Development Tools:** + * **Terminal Integration**: Built-in terminal access + * **Debugging**: Full debugging capabilities + * **Extensions**: Python, Docker, GitHub Copilot + * **Language Support**: 50+ programming languages + +===== Configuration ===== + +**Container Configuration:** +```yaml +services: + code-server: + image: lscr.io/linuxserver/code-server:latest + container_name: code-server + restart: unless-stopped + environment: + - PUID=1000 + - PGID=1000 + - TZ=${TZ} + - PASSWORD=${CODE_SERVER_PASSWORD} + - SUDO_PASSWORD=${CODE_SERVER_PASSWORD} + - PROXY_DOMAIN=${DOMAIN} + - DEFAULT_WORKSPACE=/config/workspace + volumes: + - ./code-server/config:/config + - /opt/stacks:/opt/stacks:ro + - /home/kelin/AI-Homelab:/workspace + networks: + - traefik-network + deploy: + resources: + limits: + cpus: '1.0' + memory: 1G + reservations: + cpus: '0.2' + memory: 256M + labels: + - "traefik.enable=true" + - "traefik.http.routers.code-server.rule=Host(`code.${DOMAIN}`)" + - "traefik.http.routers.code-server.entrypoints=websecure" + - "traefik.http.routers.code-server.tls.certresolver=letsencrypt" + - "traefik.http.routers.code-server.middlewares=authelia@docker" + - "traefik.http.services.code-server.loadbalancer.server.port=8443" + - "x-dockge.url=https://code.${DOMAIN}" +``` + +**Environment Variables:** +```bash +# User permissions +PUID=1000 +PGID=1000 + +# Authentication +PASSWORD=your-secure-password +SUDO_PASSWORD=your-secure-password + +# Domain configuration +PROXY_DOMAIN=yourdomain.duckdns.org + +# Default workspace +DEFAULT_WORKSPACE=/config/workspace +``` + +===== Getting Started ===== + +**Initial Access:** + 1. **Access URL**: Visit https://code.yourdomain.duckdns.org + 2. **Authelia Login**: Authenticate with SSO + 3. **Password Setup**: Enter container password + 4. **Workspace Setup**: Configure your workspace + +**Interface Overview:** + * **Explorer**: File and folder navigation + * **Editor**: Code editing with syntax highlighting + * **Terminal**: Integrated command line access + * **Extensions**: VS Code extension marketplace + * **Settings**: Full VS Code configuration + +===== Workspace Configuration ===== + +**Directory Mounting:** +```yaml +volumes: + # AI-Homelab repository + - /home/kelin/AI-Homelab:/workspace + + # Stack configurations + - /opt/stacks:/opt/stacks:ro + + # User configuration + - ./code-server/config:/config +``` + +**Workspace Settings:** +```json +// .vscode/settings.json in workspace +{ + "python.defaultInterpreterPath": "/usr/bin/python3", + "git.enableSmartCommit": true, + "editor.formatOnSave": true, + "terminal.integrated.shell.linux": "/bin/bash" +} +``` + +**Recommended Extensions:** + * **GitHub Copilot**: AI-powered code completion + * **Python**: Python language support + * **Docker**: Container management + * **GitLens**: Enhanced Git capabilities + * **Remote SSH**: Remote development + +===== Development Workflow ===== + +**Homelab Development:** + * **Stack Editing**: Edit docker-compose.yml files + * **Configuration Management**: Modify service configurations + * **Script Development**: Create automation scripts + * **Documentation**: Edit wiki and documentation + +**AI Integration:** + * **GitHub Copilot**: AI-powered code suggestions + * **AI Toolkit**: Access to AI development tools + * **Model Testing**: Test AI models and integrations + * **Workflow Development**: Create AI agent workflows + +**Version Control:** + * **Git Integration**: Full Git repository management + * **Branch Management**: Create and manage branches + * **Commit Management**: Stage, commit, and push changes + * **Conflict Resolution**: Handle merge conflicts + +===== Extensions & Customization ===== + +**Essential Extensions:** +```json +{ + "recommendations": [ + "ms-python.python", + "ms-vscode.vscode-json", + "ms-vscode-remote.remote-ssh", + "GitHub.copilot", + "ms-vscode.vscode-docker", + "eamodio.gitlens", + "ms-vscode.vscode-yaml", + "redhat.vscode-yaml" + ] +} +``` + +**Theme Configuration:** +```json +// Dark theme with high contrast +{ + "workbench.colorTheme": "Default Dark Modern", + "editor.fontSize": 14, + "editor.lineHeight": 1.6, + "terminal.integrated.fontSize": 13 +} +``` + +**Keybindings:** +```json +// Custom keybindings +[ + { + "key": "ctrl+shift+t", + "command": "workbench.action.terminal.new" + }, + { + "key": "ctrl+shift+g", + "command": "gitlens.showCommitSearch" + } +] +``` + +===== Terminal Integration ===== + +**Terminal Configuration:** +```json +{ + "terminal.integrated.shell.linux": "/bin/bash", + "terminal.integrated.cwd": "/workspace", + "terminal.integrated.env.linux": { + "PATH": "/usr/local/bin:/usr/bin:/bin" + } +} +``` + +**Docker Commands:** +```bash +# Access from terminal +docker ps +docker logs container-name +docker exec -it container-name /bin/bash +``` + +**Development Commands:** +```bash +# Python development +python3 -m venv venv +source venv/bin/activate +pip install -r requirements.txt + +# Git operations +git status +git add . +git commit -m "Update" +git push origin main +``` + +===== Security Considerations ===== + +**Access Control:** + * **Authelia Protection**: SSO authentication required + * **Password Protection**: Additional container password + * **Network Isolation**: Container network restrictions + * **File Permissions**: Proper user permission mapping + +**Data Protection:** + * **Workspace Security**: Secure workspace access + * **Git Credentials**: Secure Git authentication + * **Extension Security**: Verify extension sources + * **Session Security**: Secure web sessions + +===== Performance Optimization ===== + +**Resource Management:** +```yaml +deploy: + resources: + limits: + cpus: '1.0' + memory: 1G + reservations: + cpus: '0.2' + memory: 256M +``` + +**Performance Tuning:** + * **Extension Management**: Limit active extensions + * **File Watching**: Configure file watcher limits + * **Memory Usage**: Monitor memory consumption + * **Caching**: Enable appropriate caching + +===== Troubleshooting ===== + +**Connection Issues:** +```bash +# Check service status +docker ps | grep code-server + +# View logs +docker logs code-server + +# Test web access +curl -k https://code.yourdomain.duckdns.org +``` + +**Extension Problems:** + * **Installation Failures**: Check network connectivity + * **Compatibility Issues**: Verify VS Code version compatibility + * **Permission Errors**: Check file permissions + * **Cache Issues**: Clear extension cache + +**Workspace Issues:** + * **File Access**: Verify volume mount permissions + * **Git Problems**: Check Git configuration + * **Python Issues**: Verify Python interpreter path + * **Extension Sync**: Check settings synchronization + +**Performance Issues:** + * **High CPU Usage**: Reduce active extensions + * **Memory Problems**: Increase memory limits + * **Slow Loading**: Clear browser cache + * **Network Latency**: Check network performance + +**Troubleshooting Steps:** + 1. **Check logs**: `docker logs code-server` + 2. **Verify configuration**: Check environment variables + 3. **Test connectivity**: Access web interface + 4. **Clear cache**: Clear browser and extension cache + 5. **Restart service**: `docker restart code-server` + +===== Integration with Homelab ===== + +**Stack Management:** + * **Compose Editing**: Edit docker-compose.yml files + * **Configuration Management**: Modify service settings + * **Script Development**: Create deployment scripts + * **Documentation**: Update wiki and docs + +**AI Development:** + * **Model Testing**: Test AI models in isolated environment + * **Workflow Development**: Create AI agent workflows + * **API Integration**: Develop API integrations + * **Tool Development**: Build custom tools and extensions + +**Monitoring & Debugging:** + * **Log Analysis**: Analyze service logs + * **Performance Monitoring**: Monitor system performance + * **Network Debugging**: Debug network connectivity + * **Container Debugging**: Debug containerized applications + +===== Best Practices ===== + +**Workspace Organization:** + * **Project Structure**: Maintain clean project structure + * **Version Control**: Use Git for all projects + * **Documentation**: Document code and configurations + * **Backup**: Regular workspace backups + +**Development Workflow:** + * **Branch Strategy**: Use feature branches + * **Code Reviews**: Review code changes + * **Testing**: Test changes before deployment + * **Documentation**: Update documentation + +**Security:** + * **Access Control**: Limit workspace access + * **Credential Management**: Secure sensitive credentials + * **Extension Verification**: Only trusted extensions + * **Session Management**: Proper session handling + +**Performance:** + * **Resource Limits**: Appropriate resource allocation + * **Extension Management**: Keep extensions updated + * **Cache Management**: Regular cache cleanup + * **Optimization**: Optimize for your use case + +===== Use Cases ===== + +**Homelab Management:** + * **Service Configuration**: Edit service configurations + * **Script Development**: Create automation scripts + * **Documentation**: Maintain project documentation + * **Troubleshooting**: Debug homelab issues + +**Development Work:** + * **Code Development**: Full-stack development + * **API Development**: Build and test APIs + * **Testing**: Unit and integration testing + * **Debugging**: Application debugging + +**Remote Development:** + * **Mobile Development**: Code on mobile devices + * **Travel Access**: Access code while traveling + * **Collaborative Work**: Share development environment + * **Backup Access**: Access code from any location + +**Education & Learning:** + * **Tutorial Following**: Follow coding tutorials + * **Experimentation**: Test new technologies + * **Documentation**: Create learning materials + * **Project Development**: Build personal projects + +===== Advanced Configuration ===== + +**Custom Extensions:** +```json +// Install custom extensions +{ + "extensions": { + "recommendations": [ + "ms-python.python", + "GitHub.copilot" + ] + } +} +``` + +**Remote Development:** +```json +// SSH configuration for remote development +{ + "remote.SSH.configFile": "~/.ssh/config", + "remote.SSH.remotePlatform": { + "homelab-server": "linux" + } +} +``` + +**Task Automation:** +```json +// tasks.json for automation +{ + "version": "2.0.0", + "tasks": [ + { + "label": "Deploy Stack", + "type": "shell", + "command": "docker-compose", + "args": ["up", "-d"], + "group": "build" + } + ] +} +``` + +Code Server provides a full-featured development environment in your browser, perfectly integrated with your homelab workflow and AI development tools. + +**Next:** Learn about [[services:infrastructure:docker-proxy|Docker Proxy]] or explore [[getting_started:access|Access Guide]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/infrastructure/docker-proxy.txt b/config-templates/dokuwiki/data/pages/services/infrastructure/docker-proxy.txt new file mode 100644 index 0000000..8f80213 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/infrastructure/docker-proxy.txt @@ -0,0 +1,384 @@ +====== Docker Proxy ====== + +Docker Proxy provides secure remote access to the Docker daemon socket, enabling safe Docker API access from external tools and services. It acts as a secure proxy between Docker clients and the Docker daemon. + +===== Overview ===== + +**Purpose:** Secure Docker socket proxy +**Deployment:** Infrastructure stack +**Access Method:** TCP socket (no web UI) +**Security:** TLS encryption and authentication +**Integration:** External Docker tool access + +===== Key Features ===== + +**Secure Access:** + * **TLS Encryption**: Encrypted Docker API communication + * **Authentication**: Client certificate authentication + * **Access Control**: Granular permission control + * **Audit Logging**: Comprehensive access logging + +**Proxy Features:** + * **Socket Proxy**: TCP proxy for Docker socket + * **API Compatibility**: Full Docker API support + * **Connection Pooling**: Efficient connection management + * **Load Balancing**: Distribute requests across instances + +**Monitoring:** + * **Request Logging**: Log all Docker API requests + * **Performance Metrics**: Monitor proxy performance + * **Health Checks**: Proxy health monitoring + * **Error Tracking**: Track and report errors + +===== Configuration ===== + +**Container Configuration:** +```yaml +services: + docker-proxy: + image: tecnativa/docker-socket-proxy:latest + container_name: docker-proxy + restart: unless-stopped + environment: + - CONTAINERS=1 + - SERVICES=1 + - TASKS=1 + - NODES=0 + - SWARM=0 + - NETWORKS=0 + - VOLUMES=0 + - IMAGES=0 + - EXEC=0 + - INFO=1 + - VERSION=1 + - PING=1 + - BUILD=0 + - COMMIT=0 + - CONFIGS=0 + - DISTRIBUTION=0 + - EVENTS=1 + - GRPC=0 + - LOGS=1 + - PLUGINS=0 + - POST=0 + - SECRETS=0 + - SESSION=0 + - SYSTEM=0 + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + ports: + - 2376:2376 + networks: + - traefik-network + deploy: + resources: + limits: + cpus: '0.2' + memory: 64M + reservations: + cpus: '0.01' + memory: 16M +``` + +**Permission Levels:** +```bash +# Read-only access (recommended) +CONTAINERS=1 # List containers +SERVICES=1 # List services +TASKS=1 # List tasks +INFO=1 # System info +VERSION=1 # Version info +PING=1 # Health checks +EVENTS=1 # Docker events +LOGS=1 # Container logs + +# Write access (use carefully) +IMAGES=1 # Pull/push images +NETWORKS=1 # Network management +VOLUMES=1 # Volume management +EXEC=1 # Execute commands +BUILD=1 # Build images +POST=1 # Create resources +``` + +===== Security Configuration ===== + +**TLS Setup:** +```yaml +# Generate certificates +openssl req -new -newkey rsa:4096 -days 365 -nodes -x509 \ + -subj "/C=US/ST=State/L=City/O=Organization/CN=docker-proxy" \ + -keyout docker-proxy.key -out docker-proxy.crt + +# Mount certificates +volumes: + - ./certs/docker-proxy.crt:/certs/server.crt:ro + - ./certs/docker-proxy.key:/certs/server.key:ro +``` + +**Client Authentication:** +```bash +# Client certificate authentication +environment: + - AUTH=1 + - CERTS_PATH=/certs + +volumes: + - ./certs:/certs:ro +``` + +**Access Control:** + * **IP Whitelisting**: Restrict access by IP address + * **Certificate Validation**: Require valid client certificates + * **Permission Levels**: Granular API permission control + * **Rate Limiting**: Prevent abuse and DoS attacks + +===== Usage Examples ===== + +**Docker Client Connection:** +```bash +# Connect using TCP +export DOCKER_HOST=tcp://localhost:2376 +docker ps + +# With TLS +export DOCKER_HOST=tcp://localhost:2376 +export DOCKER_TLS_VERIFY=1 +export DOCKER_CERT_PATH=/path/to/certs +docker ps +``` + +**External Tool Integration:** +```python +# Python Docker client +import docker + +client = docker.DockerClient(base_url='tcp://localhost:2376') +containers = client.containers.list() +``` + +**CI/CD Integration:** +```yaml +# GitHub Actions example +- name: Connect to Docker + run: | + echo "DOCKER_HOST=tcp://docker-proxy:2376" >> $GITHUB_ENV + docker ps +``` + +**Monitoring Integration:** +```bash +# Prometheus metrics +curl http://localhost:2376/metrics + +# Health check +curl http://localhost:2376/_ping +``` + +===== Monitoring & Troubleshooting ===== + +**Proxy Logs:** +```bash +# View proxy logs +docker logs docker-proxy + +# Follow logs in real-time +docker logs -f docker-proxy +``` + +**Connection Testing:** +```bash +# Test basic connectivity +telnet localhost 2376 + +# Test Docker API +curl http://localhost:2376/_ping + +# Test with Docker client +DOCKER_HOST=tcp://localhost:2376 docker version +``` + +**Permission Issues:** + * **Access Denied**: Check permission environment variables + * **Certificate Errors**: Verify TLS certificate configuration + * **Network Issues**: Check firewall and network connectivity + * **Socket Access**: Verify Docker socket permissions + +**Performance Issues:** + * **High Latency**: Check network configuration + * **Connection Limits**: Monitor concurrent connections + * **Resource Usage**: Check CPU/memory usage + * **Rate Limiting**: Adjust rate limiting settings + +**Troubleshooting Steps:** + 1. **Check logs**: `docker logs docker-proxy` + 2. **Test connectivity**: Verify TCP connection + 3. **Validate permissions**: Check environment variables + 4. **Test Docker client**: Verify Docker API access + 5. **Restart service**: `docker restart docker-proxy` + +===== Advanced Configuration ===== + +**High Availability:** +```yaml +# Multiple proxy instances +services: + docker-proxy-1: + # Configuration for instance 1 + + docker-proxy-2: + # Configuration for instance 2 + + load-balancer: + # Load balancer configuration +``` + +**Custom TLS Configuration:** +```yaml +environment: + - TLS_CERT=/certs/custom.crt + - TLS_KEY=/certs/custom.key + - TLS_CA=/certs/ca.crt +``` + +**Rate Limiting:** +```yaml +environment: + - RATE_LIMIT=100 # Requests per minute + - BURST_LIMIT=20 # Burst allowance +``` + +**Audit Logging:** +```yaml +environment: + - LOG_LEVEL=debug + - AUDIT_LOG=/logs/audit.log + +volumes: + - ./logs:/logs +``` + +===== Security Best Practices ===== + +**Access Control:** + * **Principle of Least Privilege**: Grant minimal required permissions + * **Network Segmentation**: Isolate proxy network access + * **Certificate Management**: Regular certificate rotation + * **Monitoring**: Continuous access monitoring + +**TLS Security:** + * **Strong Ciphers**: Use modern TLS cipher suites + * **Certificate Validation**: Enable client certificate validation + * **Perfect Forward Secrecy**: Enable PFS cipher suites + * **Regular Updates**: Keep TLS libraries updated + +**Operational Security:** + * **Log Analysis**: Regular security log review + * **Intrusion Detection**: Monitor for suspicious activity + * **Backup Security**: Secure configuration backups + * **Incident Response**: Have security incident procedures + +===== Integration Patterns ===== + +**CI/CD Pipelines:** +```yaml +# Jenkins pipeline +pipeline { + agent any + stages { + stage('Build') { + steps { + script { + docker.withServer('tcp://docker-proxy:2376') { + docker.build('my-app') + } + } + } + } + } +} +``` + +**Monitoring Integration:** +```yaml +# Prometheus configuration +scrape_configs: + - job_name: 'docker-proxy' + static_configs: + - targets: ['docker-proxy:2376'] + metrics_path: '/metrics' +``` + +**Backup Integration:** +```bash +# Backup Docker configurations +DOCKER_HOST=tcp://localhost:2376 docker system info > system-info.json +DOCKER_HOST=tcp://localhost:2376 docker config ls > configs.json +``` + +===== Performance Optimization ===== + +**Resource Management:** +```yaml +deploy: + resources: + limits: + cpus: '0.2' + memory: 64M + reservations: + cpus: '0.01' + memory: 16M +``` + +**Connection Optimization:** + * **Connection Pooling**: Reuse connections efficiently + * **Timeout Configuration**: Appropriate request timeouts + * **Concurrent Limits**: Control simultaneous connections + * **Caching**: Cache frequently accessed data + +===== Use Cases ===== + +**Development Environments:** + * **Remote Docker Access**: Access Docker from development machines + * **CI/CD Integration**: Integrate with build pipelines + * **Testing Environments**: Isolated testing environments + * **Container Management**: Manage containers from external tools + +**Production Management:** + * **Monitoring Tools**: Connect monitoring tools to Docker API + * **Management Platforms**: Integrate with Docker management platforms + * **Backup Solutions**: Connect backup tools to Docker + * **Security Scanning**: Integrate security scanning tools + +**Homelab Management:** + * **Portainer Integration**: Connect Portainer to Docker API + * **External Tools**: Use Docker CLI from external machines + * **Automation Scripts**: Run Docker automation scripts + * **Monitoring Integration**: Connect monitoring stacks + +**Enterprise Integration:** + * **Centralized Management**: Connect to enterprise Docker platforms + * **Compliance Monitoring**: Meet compliance requirements + * **Audit Trails**: Maintain Docker operation audit logs + * **Security Integration**: Integrate with security platforms + +===== Backup & Recovery ===== + +**Configuration Backup:** +```bash +# Backup proxy configuration +docker run --rm \ + -v docker-proxy-config:/config \ + -v $(pwd)/backup:/backup \ + busybox tar czf /backup/docker-proxy-config.tar.gz /config +``` + +**Certificate Management:** + * **Certificate Backup**: Regular certificate backups + * **Key Rotation**: Periodic key rotation procedures + * **Certificate Monitoring**: Monitor certificate expiration + * **Renewal Process**: Automated certificate renewal + +Docker Proxy provides secure, controlled access to the Docker daemon, enabling safe integration with external tools and services while maintaining security and audit capabilities. + +**Next:** Explore [[services:media:start|Media Services]] or return to [[services:start|Services Overview]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/infrastructure/dockge.txt b/config-templates/dokuwiki/data/pages/services/infrastructure/dockge.txt new file mode 100644 index 0000000..2b0ca34 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/infrastructure/dockge.txt @@ -0,0 +1,313 @@ +====== Dockge ====== + +Dockge is the primary web-based interface for managing Docker stacks in your homelab. It provides a clean, intuitive way to deploy, monitor, and manage all your services through a web UI, making it the central hub for homelab management. + +===== Overview ===== + +**Purpose:** Docker stack management interface +**URL:** https://dockge.yourdomain.duckdns.org +**Authentication:** Authelia SSO protected +**Deployment:** Infrastructure stack +**Interface:** Modern web UI with drag-and-drop + +===== Key Features ===== + +**Stack Management:** + * **Visual Interface**: Web-based stack management + * **Compose File Editing**: Direct YAML editing + * **One-Click Deploy**: Deploy stacks with single click + * **Real-time Monitoring**: Live container status + +**Container Operations:** + * **Start/Stop/Restart**: Individual container control + * **Log Viewing**: Integrated log viewer + * **Resource Monitoring**: CPU/memory usage + * **Network Inspection**: Container networking info + +**File Management:** + * **Directory Browser**: Navigate stack directories + * **File Editor**: Edit configuration files + * **Upload/Download**: File transfer capabilities + * **Backup Integration**: Stack backup/restore + +===== Configuration ===== + +**Container Configuration:** +```yaml +services: + dockge: + image: louislam/dockge:1 + container_name: dockge + restart: unless-stopped + environment: + - DOCKGE_STACKS_DIR=/opt/stacks + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + - /opt/stacks:/opt/stacks + - ./dockge/data:/app/data + ports: + - 5001:5001 + networks: + - traefik-network + deploy: + resources: + limits: + cpus: '0.5' + memory: 256M + reservations: + cpus: '0.1' + memory: 64M + labels: + - "traefik.enable=true" + - "traefik.http.routers.dockge.rule=Host(`dockge.${DOMAIN}`)" + - "traefik.http.routers.dockge.entrypoints=websecure" + - "traefik.http.routers.dockge.tls.certresolver=letsencrypt" + - "traefik.http.routers.dockge.middlewares=authelia@docker" + - "traefik.http.services.dockge.loadbalancer.server.port=5001" + - "x-dockge.url=https://dockge.${DOMAIN}" +``` + +**Directory Structure:** +``` +/opt/stacks/ +├── core/ # Core infrastructure +├── infrastructure/ # Management tools +├── media/ # Media services +├── media-management/ # Download automation +├── dashboards/ # Dashboard services +├── homeassistant/ # Home automation +├── productivity/ # Office tools +├── monitoring/ # Observability +├── utilities/ # Backup/utilities +└── development/ # Dev tools +``` + +===== Getting Started ===== + +**Initial Access:** + 1. **Deploy Infrastructure Stack**: Run deploy script or manual deployment + 2. **Access URL**: Visit https://dockge.yourdomain.duckdns.org + 3. **Authelia Login**: Authenticate with your credentials + 4. **First Stack**: Create your first stack + +**Interface Overview:** + * **Left Sidebar**: Stack categories and navigation + * **Main Panel**: Stack list with status indicators + * **Top Bar**: Search, settings, and actions + * **Stack Cards**: Individual stack management + +===== Stack Operations ===== + +**Creating a New Stack:** + 1. **Click "Compose"**: Open compose file editor + 2. **Enter Stack Name**: Choose directory name + 3. **Paste YAML**: Copy docker-compose.yml content + 4. **Deploy**: Click deploy button + 5. **Monitor**: Watch deployment progress + +**Managing Existing Stacks:** + * **Start/Stop**: Control stack lifecycle + * **Update**: Pull new images and restart + * **Edit**: Modify compose files + * **Logs**: View container logs + * **Terminal**: Access container shells + +**Stack Status Indicators:** + * **🟢 Running**: All containers healthy + * **🟡 Partial**: Some containers issues + * **🔴 Stopped**: Stack not running + * **🔵 Updating**: Stack being updated + +===== File Management ===== + +**Directory Navigation:** + * **Browse Stacks**: Navigate /opt/stacks directory + * **File Editor**: Edit YAML, config files + * **Upload Files**: Drag-and-drop file uploads + * **Download**: Download files from containers + +**Configuration Editing:** + * **Syntax Highlighting**: YAML, JSON, text files + * **Save Changes**: Auto-save or manual save + * **Version Control**: Track file changes + * **Backup**: Automatic file backups + +===== Container Management ===== + +**Individual Container Control:** + * **Start/Stop/Restart**: Container lifecycle + * **Logs**: Real-time log streaming + * **Exec**: Run commands in containers + * **Inspect**: View container details + +**Resource Monitoring:** + * **CPU Usage**: Real-time CPU monitoring + * **Memory Usage**: RAM consumption tracking + * **Network I/O**: Traffic monitoring + * **Disk Usage**: Storage utilization + +===== Advanced Features ===== + +**Environment Variables:** +```yaml +# Global environment file +# /opt/stacks/.env +DOMAIN=yourdomain.duckdns.org +PUID=1000 +PGID=1000 +TZ=America/New_York +``` + +**Stack Dependencies:** + * **Service Dependencies**: depends_on configuration + * **Network Dependencies**: Shared networks + * **Volume Dependencies**: Shared storage + * **Health Checks**: Service readiness + +**Backup & Restore:** + * **Stack Export**: Download compose files + * **Configuration Backup**: Environment files + * **Volume Backup**: Data persistence + * **Full Restore**: Complete stack recovery + +===== Integration with AI Assistant ===== + +**AI-Powered Management:** + * **Service Creation**: AI generates compose files + * **Configuration Help**: AI assists with setup + * **Troubleshooting**: AI analyzes logs and issues + * **Documentation**: AI maintains service docs + +**Workflow Integration:** + * **VS Code**: Direct file editing + * **GitHub Copilot**: AI assistance for configurations + * **Automated Deployments**: Script-based stack management + * **Monitoring Integration**: Health check automation + +===== Security Considerations ===== + +**Access Control:** + * **Authelia Protection**: SSO authentication required + * **User Permissions**: Container user mapping (PUID/PGID) + * **Docker Socket**: Read-only access to Docker API + * **Network Isolation**: Container network segmentation + +**Data Protection:** + * **Encrypted Connections**: HTTPS via Traefik + * **Secure Storage**: Sensitive data in environment files + * **Backup Security**: Encrypted backup storage + * **Access Logging**: User action auditing + +===== Performance Optimization ===== + +**Resource Management:** +```yaml +deploy: + resources: + limits: + cpus: '0.5' + memory: 256M + reservations: + cpus: '0.1' + memory: 64M +``` + +**Container Optimization:** + * **Image Updates**: Regular security updates + * **Log Rotation**: Prevent disk space issues + * **Cache Management**: Docker layer caching + * **Network Efficiency**: Optimized container networking + +===== Troubleshooting ===== + +**Common Issues:** + +**Cannot Connect to Docker:** +```bash +# Check Docker socket permissions +ls -la /var/run/docker.sock + +# Verify Docker is running +docker ps + +# Check container logs +docker logs dockge +``` + +**Stack Deployment Fails:** + * **YAML Syntax**: Validate compose file syntax + * **Port Conflicts**: Check for port usage conflicts + * **Network Issues**: Verify network connectivity + * **Permission Errors**: Check file/directory permissions + +**Web Interface Issues:** + * **Traefik Routing**: Verify Traefik configuration + * **Authelia Access**: Check SSO authentication + * **SSL Certificates**: Validate certificate status + * **Browser Cache**: Clear browser cache + +**Troubleshooting Steps:** + 1. **Check logs**: `docker logs dockge` + 2. **Validate configuration**: Test compose file syntax + 3. **Network connectivity**: Verify Docker network access + 4. **Restart service**: `docker restart dockge` + 5. **Check dependencies**: Ensure required services running + +===== Best Practices ===== + +**Stack Organization:** + * **Logical Grouping**: Group related services + * **Naming Convention**: Consistent naming patterns + * **Documentation**: Comment complex configurations + * **Version Control**: Track configuration changes + +**Maintenance:** + * **Regular Updates**: Keep images updated + * **Backup Routine**: Regular configuration backups + * **Log Monitoring**: Review logs for issues + * **Performance Tuning**: Optimize resource usage + +**Security:** + * **Access Control**: Limit user permissions + * **Network Security**: Use secure networks + * **Data Encryption**: Encrypt sensitive data + * **Audit Logging**: Monitor access and changes + +**Workflow:** + * **Testing**: Test changes in development first + * **Documentation**: Document custom configurations + * **Automation**: Use scripts for repetitive tasks + * **Monitoring**: Monitor stack health continuously + +===== Integration Examples ===== + +**Adding a New Service:** +```yaml +# 1. Create new stack directory +# 2. Add docker-compose.yml +# 3. Configure environment variables +# 4. Deploy via Dockge UI +# 5. Test service functionality +``` + +**Service Updates:** +```yaml +# 1. Edit compose file in Dockge +# 2. Update image version +# 3. Deploy changes +# 4. Monitor startup logs +# 5. Verify functionality +``` + +**Backup Strategy:** +```yaml +# 1. Export stack configurations +# 2. Backup environment files +# 3. Backup persistent volumes +# 4. Store backups securely +# 5. Test restore procedures +``` + +Dockge serves as the central nervous system of your homelab, providing intuitive management of all your Docker services through a modern web interface. + +**Next:** Learn about [[services:infrastructure:pihole|Pi-hole]] or explore [[getting_started:deployment|Deployment Guide]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/infrastructure/dozzle.txt b/config-templates/dokuwiki/data/pages/services/infrastructure/dozzle.txt new file mode 100644 index 0000000..7b88972 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/infrastructure/dozzle.txt @@ -0,0 +1,343 @@ +====== Dozzle ====== + +Dozzle is a real-time log viewer for Docker containers, providing a web-based interface to monitor and search through container logs. It offers live log streaming, filtering capabilities, and multi-container log management. + +===== Overview ===== + +**Purpose:** Real-time Docker log viewer +**URL:** https://dozzle.yourdomain.duckdns.org +**Authentication:** Authelia SSO protected +**Deployment:** Infrastructure stack +**Interface:** Modern web UI with live updates + +===== Key Features ===== + +**Log Viewing:** + * **Real-time Streaming**: Live log updates + * **Multi-container**: View multiple containers simultaneously + * **Search & Filter**: Advanced log filtering + * **Color Coding**: Syntax highlighting for different log levels + +**Container Management:** + * **Container List**: All running containers + * **Status Indicators**: Container health status + * **Quick Actions**: Start/stop/restart containers + * **Resource Monitoring**: Basic CPU/memory stats + +**Search & Filtering:** + * **Text Search**: Search within logs + * **Regex Support**: Regular expression filtering + * **Date Filtering**: Time-based log filtering + * **Container Filtering**: Filter by specific containers + +===== Configuration ===== + +**Container Configuration:** +```yaml +services: + dozzle: + image: amir20/dozzle:latest + container_name: dozzle + restart: unless-stopped + environment: + - DOZZLE_USERNAME=${DOZZLE_USERNAME:-admin} + - DOZZLE_PASSWORD=${DOZZLE_PASSWORD} + - DOZZLE_LEVEL=info + - DOZZLE_TAILSIZE=100 + - DOZZLE_FILTER_CONTAINERS=${DOZZLE_FILTER_CONTAINERS} + - DOZZLE_NO_ANALYTICS=true + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + networks: + - traefik-network + deploy: + resources: + limits: + cpus: '0.3' + memory: 128M + reservations: + cpus: '0.05' + memory: 32M + labels: + - "traefik.enable=true" + - "traefik.http.routers.dozzle.rule=Host(`dozzle.${DOMAIN}`)" + - "traefik.http.routers.dozzle.entrypoints=websecure" + - "traefik.http.routers.dozzle.tls.certresolver=letsencrypt" + - "traefik.http.routers.dozzle.middlewares=authelia@docker" + - "traefik.http.services.dozzle.loadbalancer.server.port=8080" + - "x-dockge.url=https://dozzle.${DOMAIN}" +``` + +**Environment Variables:** +```bash +# Authentication (optional, Authelia handles SSO) +DOZZLE_USERNAME=admin +DOZZLE_PASSWORD=your-secure-password + +# Logging configuration +DOZZLE_LEVEL=info # debug, info, warn, error +DOZZLE_TAILSIZE=100 # Lines to show initially + +# Container filtering (optional) +DOZZLE_FILTER_CONTAINERS=container1,container2 + +# Privacy +DOZZLE_NO_ANALYTICS=true +``` + +===== Interface Overview ===== + +**Main Dashboard:** + * **Container List**: Left sidebar with all containers + * **Log Viewer**: Main panel showing selected logs + * **Search Bar**: Top search and filter controls + * **Status Bar**: Connection and filter status + +**Container Selection:** + * **Single Container**: Click to view individual logs + * **Multiple Containers**: Hold Ctrl/Cmd to select multiple + * **All Containers**: View logs from all containers + * **Container Groups**: Filter by stack or service type + +**Log Display:** + * **Live Updates**: Real-time log streaming + * **Color Coding**: Different colors for log levels + * **Timestamps**: Show log timestamps + * **Line Numbers**: Reference specific log lines + +===== Search & Filtering ===== + +**Text Search:** +```bash +# Basic search +error warning + +# Case-sensitive search +/Error|Warning/ + +# Complex patterns +"connection refused" OR "timeout" +``` + +**Advanced Filtering:** + * **Container Name**: Filter by specific containers + * **Log Level**: Filter by severity (ERROR, WARN, INFO, DEBUG) + * **Time Range**: Show logs from specific time periods + * **Regex Patterns**: Use regular expressions for complex matching + +**Saved Filters:** + * **Custom Filters**: Save frequently used search patterns + * **Filter Presets**: Pre-configured filter combinations + * **Quick Filters**: One-click common filters (errors only, etc.) + +===== Container Management ===== + +**Quick Actions:** + * **Start/Stop**: Control container lifecycle + * **Restart**: Restart individual containers + * **Logs**: Jump to detailed logs + * **Exec**: Open terminal in container + +**Container Information:** + * **Status**: Running, stopped, paused + * **Uptime**: How long container has been running + * **Image**: Container image and version + * **Ports**: Exposed ports and mappings + +**Resource Monitoring:** + * **CPU Usage**: Real-time CPU percentage + * **Memory Usage**: RAM consumption + * **Network I/O**: Data transfer rates + * **Disk I/O**: Storage read/write operations + +===== Advanced Features ===== + +**Log Analysis:** + * **Pattern Recognition**: Identify common error patterns + * **Anomaly Detection**: Flag unusual log patterns + * **Trend Analysis**: Track log volume over time + * **Alert Integration**: Send alerts for specific log patterns + +**Export & Sharing:** + * **Log Export**: Download logs as text files + * **Share Links**: Generate shareable log links + * **API Access**: Programmatic log access + * **Integration**: Connect with other monitoring tools + +**Customization:** + * **Themes**: Light/dark mode switching + * **Layout**: Customizable interface layout + * **Shortcuts**: Keyboard shortcuts for common actions + * **Notifications**: Browser notifications for events + +===== Security Considerations ===== + +**Access Control:** + * **Authelia Protection**: SSO authentication required + * **User Permissions**: Container access restrictions + * **Log Privacy**: Sensitive data in logs + * **Network Security**: Secure Docker socket access + +**Data Protection:** + * **Log Encryption**: Secure log transmission + * **Access Logging**: Audit log access + * **Data Retention**: Log retention policies + * **Privacy Controls**: Filter sensitive information + +===== Performance Optimization ===== + +**Resource Management:** +```yaml +deploy: + resources: + limits: + cpus: '0.3' + memory: 128M + reservations: + cpus: '0.05' + memory: 32M +``` + +**Log Optimization:** + * **Tail Size**: Limit initial log display + * **Buffer Management**: Efficient log buffering + * **Compression**: Log compression for storage + * **Cleanup**: Automatic old log cleanup + +**Container Filtering:** +```yaml +# Limit visible containers +environment: + - DOZZLE_FILTER_CONTAINERS=traefik,authelia,dockge +``` + +===== Troubleshooting ===== + +**Connection Issues:** +```bash +# Check Docker socket access +ls -la /var/run/docker.sock + +# Verify Docker is running +docker ps + +# Check container logs +docker logs dozzle +``` + +**Log Display Problems:** + * **No Logs Showing**: Check container permissions + * **Logs Not Updating**: Verify real-time connection + * **Search Not Working**: Check search syntax + * **Performance Issues**: Reduce number of containers + +**Authentication Issues:** + * **Login Problems**: Verify credentials + * **Authelia Integration**: Check SSO configuration + * **Session Timeout**: Adjust session settings + * **Permission Denied**: Check user permissions + +**Web Interface Issues:** + * **Page Not Loading**: Check Traefik routing + * **SSL Errors**: Verify certificate status + * **JavaScript Errors**: Clear browser cache + * **Mobile Issues**: Check responsive design + +**Troubleshooting Steps:** + 1. **Check logs**: `docker logs dozzle` + 2. **Test connectivity**: Verify Docker socket access + 3. **Validate configuration**: Check environment variables + 4. **Browser testing**: Test in different browsers + 5. **Restart service**: `docker restart dozzle` + +===== Integration with Monitoring ===== + +**Prometheus Integration:** +```yaml +# Expose metrics for monitoring +environment: + - DOZZLE_ENABLE_METRICS=true + - DOZZLE_METRICS_PORT=8081 +``` + +**Grafana Dashboards:** + * **Log Volume**: Track log generation rates + * **Error Rates**: Monitor error log frequency + * **Container Health**: Track container status + * **Performance Metrics**: CPU/memory usage trends + +**Alert Integration:** + * **Error Alerts**: Alert on specific error patterns + * **Container Alerts**: Notify on container failures + * **Performance Alerts**: Alert on resource issues + * **Log Volume Alerts**: Alert on unusual log activity + +===== Best Practices ===== + +**Log Management:** + * **Regular Monitoring**: Daily log review routine + * **Search Optimization**: Use efficient search patterns + * **Filter Usage**: Create useful filter presets + * **Export Strategy**: Regular log exports for analysis + +**Container Organization:** + * **Naming Convention**: Consistent container naming + * **Grouping**: Logical container grouping + * **Tagging**: Use labels for better organization + * **Documentation**: Document container purposes + +**Security:** + * **Access Control**: Limit log access to authorized users + * **Data Protection**: Be aware of sensitive data in logs + * **Network Security**: Secure Docker socket access + * **Audit Logging**: Track log access and searches + +**Performance:** + * **Resource Limits**: Appropriate CPU/memory limits + * **Container Filtering**: Limit visible containers + * **Log Tail Size**: Optimize initial log display + * **Caching**: Use browser caching for better performance + +===== Use Cases ===== + +**Development & Debugging:** + * **Application Logs**: Monitor application behavior + * **Error Tracking**: Quickly identify and fix errors + * **Performance Monitoring**: Track application performance + * **Integration Testing**: Verify service interactions + +**Production Monitoring:** + * **Service Health**: Monitor service availability + * **Error Detection**: Catch errors before they escalate + * **User Issue Investigation**: Debug user-reported problems + * **Security Monitoring**: Watch for suspicious activity + +**Maintenance & Troubleshooting:** + * **Update Monitoring**: Watch for issues during updates + * **Configuration Changes**: Monitor impact of changes + * **Network Issues**: Debug connectivity problems + * **Resource Problems**: Identify resource bottlenecks + +===== Keyboard Shortcuts ===== + +**Navigation:** + * **Ctrl/Cmd + K**: Focus search bar + * **Arrow Keys**: Navigate container list + * **Enter**: Select container + * **Esc**: Clear selection + +**Search:** + * **Ctrl/Cmd + F**: Start search + * **F3**: Find next occurrence + * **Shift + F3**: Find previous occurrence + * **Ctrl/Cmd + G**: Go to line + +**Actions:** + * **Ctrl/Cmd + R**: Refresh logs + * **Ctrl/Cmd + S**: Save current filter + * **Ctrl/Cmd + E**: Export logs + * **Ctrl/Cmd + T**: Open terminal + +Dozzle provides essential log monitoring capabilities with an intuitive interface, making it easy to track and troubleshoot your containerized services in real-time. + +**Next:** Learn about [[services:infrastructure:glances|Glances]] or explore [[architecture:monitoring|Monitoring Architecture]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/infrastructure/glances.txt b/config-templates/dokuwiki/data/pages/services/infrastructure/glances.txt new file mode 100644 index 0000000..3cbb384 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/infrastructure/glances.txt @@ -0,0 +1,394 @@ +====== Glances ====== + +Glances is a cross-platform system monitoring tool that provides real-time information about your system's performance, resources, and running processes. It offers a web-based interface for monitoring system health and performance metrics. + +===== Overview ===== + +**Purpose:** System and container monitoring +**URL:** https://glances.yourdomain.duckdns.org +**Authentication:** Authelia SSO protected +**Deployment:** Infrastructure stack +**Interface:** Web-based monitoring dashboard + +===== Key Features ===== + +**System Monitoring:** + * **CPU Usage**: Real-time CPU utilization + * **Memory Usage**: RAM and swap monitoring + * **Disk I/O**: Storage read/write operations + * **Network I/O**: Network traffic monitoring + +**Container Monitoring:** + * **Docker Stats**: Container resource usage + * **Container Health**: Status and health checks + * **Process Monitoring**: Running processes + * **Service Status**: Application service monitoring + +**Performance Metrics:** + * **Load Average**: System load over time + * **Temperature**: CPU and system temperatures + * **Fan Speed**: Cooling system monitoring + * **Power Usage**: System power consumption + +===== Configuration ===== + +**Container Configuration:** +```yaml +services: + glances: + image: nicolargo/glances:latest + container_name: glances + restart: unless-stopped + pid: host + environment: + - GLANCES_OPT=-w + - GLANCES_OPT_WEBserver=true + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + - /etc/os-release:/etc/os-release:ro + - /proc:/host/proc:ro + - /sys:/host/sys:ro + networks: + - traefik-network + deploy: + resources: + limits: + cpus: '0.3' + memory: 128M + reservations: + cpus: '0.05' + memory: 32M + labels: + - "traefik.enable=true" + - "traefik.http.routers.glances.rule=Host(`glances.${DOMAIN}`)" + - "traefik.http.routers.glances.entrypoints=websecure" + - "traefik.http.routers.glances.tls.certresolver=letsencrypt" + - "traefik.http.routers.glances.middlewares=authelia@docker" + - "traefik.http.services.glances.loadbalancer.server.port=61208" + - "x-dockge.url=https://glances.${DOMAIN}" +``` + +**Command Line Options:** +```bash +# Web server mode +GLANCES_OPT=-w + +# Additional options +GLANCES_OPT=-w --disable-webui-password --enable-process-extended + +# Custom refresh interval +GLANCES_OPT=-w --time 5 + +# Disable specific plugins +GLANCES_OPT=-w --disable cpu --disable mem +``` + +===== Interface Overview ===== + +**Main Dashboard:** + * **System Overview**: CPU, memory, disk, network + * **Container List**: Docker container statistics + * **Process List**: Top running processes + * **Alerts Panel**: System alerts and warnings + +**Navigation Tabs:** + * **System**: Core system metrics + * **Docker**: Container monitoring + * **Processes**: Process management + * **Alerts**: System alerts and thresholds + * **Filesystem**: Disk usage and I/O + +**Real-time Updates:** + * **Auto-refresh**: Configurable update intervals + * **Live Charts**: Real-time performance graphs + * **Color Coding**: Status-based color indicators + * **Threshold Alerts**: Configurable warning levels + +===== System Monitoring ===== + +**CPU Monitoring:** + * **Usage Percentage**: Overall CPU utilization + * **Per-Core Usage**: Individual core monitoring + * **Load Average**: 1, 5, 15-minute averages + * **CPU Frequency**: Current clock speeds + +**Memory Monitoring:** + * **RAM Usage**: Physical memory utilization + * **Swap Usage**: Swap file/page file usage + * **Memory Pressure**: System memory pressure + * **Cache Statistics**: Buffer and cache usage + +**Disk Monitoring:** + * **Usage Percentage**: Filesystem utilization + * **I/O Operations**: Read/write operations per second + * **Transfer Rates**: Data transfer speeds + * **Disk Health**: S.M.A.R.T. status (if available) + +**Network Monitoring:** + * **Interface Statistics**: Per-interface traffic + * **Connection Count**: Active network connections + * **Bandwidth Usage**: Upload/download rates + * **Network Errors**: Packet loss and errors + +===== Container Monitoring ===== + +**Docker Integration:** + * **Container List**: All running containers + * **Resource Usage**: CPU, memory per container + * **Network Stats**: Container network traffic + * **Health Status**: Container health checks + +**Container Details:** + * **Image Information**: Base image and version + * **Port Mappings**: Exposed ports + * **Volume Mounts**: Attached volumes + * **Environment Variables**: Container configuration + +**Performance Metrics:** + * **CPU Shares**: CPU allocation and usage + * **Memory Limits**: Memory constraints and usage + * **Network I/O**: Container network traffic + * **Disk I/O**: Container storage operations + +===== Process Monitoring ===== + +**Process List:** + * **Top Processes**: Most resource-intensive processes + * **Process Tree**: Parent-child process relationships + * **User Processes**: Per-user process listing + * **System Processes**: Kernel and system processes + +**Process Details:** + * **CPU Usage**: Per-process CPU consumption + * **Memory Usage**: RAM and virtual memory + * **I/O Operations**: Disk read/write activity + * **Network Activity**: Network connections + +**Process Management:** + * **Kill Process**: Terminate problematic processes + * **Change Priority**: Adjust process nice levels + * **Resource Limits**: Set process resource limits + * **Process Groups**: Group related processes + +===== Alert System ===== + +**Threshold Configuration:** +```yaml +# Alert thresholds (environment variables) +GLANCES_OPT=-w --alert cpu>80,mem>90,disk>85 +``` + +**Alert Types:** + * **CPU Alerts**: High CPU usage warnings + * **Memory Alerts**: Memory pressure alerts + * **Disk Alerts**: Storage space warnings + * **Network Alerts**: Bandwidth threshold alerts + +**Alert Actions:** + * **Visual Indicators**: Color-coded alerts + * **Sound Alerts**: Audio notifications + * **Email Notifications**: SMTP alerts + * **Webhook Integration**: External alert systems + +===== Advanced Configuration ===== + +**Custom Plugins:** +```yaml +# Enable additional plugins +GLANCES_OPT=-w --enable-plugin sensors --enable-plugin gpu +``` + +**Export Options:** +```yaml +# Export to various formats +GLANCES_OPT=-w --export csv --export-csv-file /data/stats.csv +GLANCES_OPT=-w --export influxdb --export-influxdb-host localhost +``` + +**Remote Monitoring:** +```yaml +# Monitor remote systems +GLANCES_OPT=-w --client localhost:61209 +``` + +**Configuration File:** +```yaml +# glances.conf +[main] +refresh=2 +history_size=1200 + +[cpu] +user_careful=50 +user_warning=70 +user_critical=90 +``` + +===== Security Considerations ===== + +**Access Control:** + * **Authelia Protection**: SSO authentication required + * **Network Isolation**: Container network restrictions + * **Read-only Access**: Limited system access + * **Audit Logging**: Monitor access patterns + +**Data Protection:** + * **Sensitive Data**: Avoid exposing sensitive information + * **Encryption**: Secure data transmission + * **Access Logging**: Track monitoring access + * **Privacy Controls**: Limit exposed system information + +===== Performance Optimization ===== + +**Resource Management:** +```yaml +deploy: + resources: + limits: + cpus: '0.3' + memory: 128M + reservations: + cpus: '0.05' + memory: 32M +``` + +**Monitoring Optimization:** + * **Refresh Rate**: Balance between real-time and performance + * **Data Retention**: Configure historical data limits + * **Plugin Selection**: Enable only needed monitoring plugins + * **Caching**: Use efficient data caching + +===== Troubleshooting ===== + +**Connection Issues:** +```bash +# Check web interface +curl -k https://glances.yourdomain.duckdns.org + +# Verify port accessibility +netstat -tlnp | grep 61208 + +# Check container logs +docker logs glances +``` + +**Monitoring Problems:** + * **No Data Showing**: Check system permissions + * **High Resource Usage**: Adjust refresh rates + * **Missing Metrics**: Enable required plugins + * **Inaccurate Data**: Verify system compatibility + +**Docker Integration Issues:** + * **Socket Access**: Verify Docker socket permissions + * **Container Detection**: Check Docker API access + * **Permission Errors**: Adjust container privileges + * **Network Issues**: Check container networking + +**Performance Issues:** + * **High CPU Usage**: Reduce refresh frequency + * **Memory Leaks**: Monitor memory consumption + * **Disk I/O**: Optimize data storage + * **Network Latency**: Check network performance + +**Troubleshooting Steps:** + 1. **Check logs**: `docker logs glances` + 2. **Verify configuration**: Test command line options + 3. **Test connectivity**: Check web interface access + 4. **Monitor resources**: Track system resource usage + 5. **Restart service**: `docker restart glances` + +===== Integration with Monitoring Stack ===== + +**Prometheus Integration:** +```yaml +# Export metrics to Prometheus +GLANCES_OPT=-w --export prometheus --export-prometheus-port 9091 +``` + +**Grafana Dashboards:** + * **System Overview**: CPU, memory, disk, network + * **Container Metrics**: Docker container statistics + * **Process Monitoring**: Top processes and resource usage + * **Historical Trends**: Performance over time + +**Alert Manager Integration:** + * **Threshold Alerts**: Configurable alert rules + * **Notification Channels**: Email, Slack, webhook alerts + * **Escalation Policies**: Multi-level alert handling + * **Silence Management**: Alert suppression rules + +===== Best Practices ===== + +**Monitoring Strategy:** + * **Key Metrics**: Focus on critical system metrics + * **Alert Thresholds**: Set appropriate warning levels + * **Baseline Establishment**: Understand normal system behavior + * **Trend Analysis**: Monitor performance trends + +**Alert Configuration:** + * **Avoid Alert Fatigue**: Set meaningful thresholds + * **Escalation Paths**: Define alert escalation procedures + * **Maintenance Windows**: Suppress alerts during maintenance + * **Testing**: Regularly test alert functionality + +**Performance:** + * **Resource Limits**: Appropriate CPU/memory allocation + * **Refresh Rates**: Balance real-time vs performance + * **Data Retention**: Configure appropriate history + * **Optimization**: Enable only needed features + +**Security:** + * **Access Control**: Limit monitoring access + * **Data Protection**: Secure monitoring data + * **Network Security**: Secure monitoring traffic + * **Compliance**: Meet monitoring compliance requirements + +===== Use Cases ===== + +**System Administration:** + * **Performance Monitoring**: Track system health + * **Capacity Planning**: Plan for resource upgrades + * **Troubleshooting**: Diagnose system issues + * **Maintenance Planning**: Schedule maintenance windows + +**Container Orchestration:** + * **Resource Allocation**: Monitor container resources + * **Health Checks**: Track container health + * **Scaling Decisions**: Inform scaling decisions + * **Optimization**: Optimize container performance + +**Development & Testing:** + * **Application Monitoring**: Monitor application performance + * **Resource Usage**: Track development environment usage + * **Debugging**: Identify performance bottlenecks + * **Testing**: Validate system performance + +**Production Monitoring:** + * **SLA Monitoring**: Ensure service level agreements + * **Incident Response**: Quick issue identification + * **Root Cause Analysis**: Analyze system incidents + * **Reporting**: Generate performance reports + +===== Keyboard Shortcuts ===== + +**Navigation:** + * **Tab**: Switch between sections + * **Arrow Keys**: Navigate lists and menus + * **Enter**: Select item or open details + * **Esc**: Close dialogs or return to main view + +**Actions:** + * **R**: Refresh data + * **S**: Sort current list + * **F**: Filter/search + * **H**: Show help + +**Views:** + * **1-9**: Switch to specific tabs + * **C**: Container view + * **P**: Process view + * **A**: Alerts view + +Glances provides comprehensive system and container monitoring with an intuitive web interface, essential for maintaining your homelab's health and performance. + +**Next:** Learn about [[services:infrastructure:watchtower|Watchtower]] or explore [[architecture:monitoring|Monitoring Architecture]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/infrastructure/pihole.txt b/config-templates/dokuwiki/data/pages/services/infrastructure/pihole.txt new file mode 100644 index 0000000..cb893b5 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/infrastructure/pihole.txt @@ -0,0 +1,376 @@ +====== Pi-hole ====== + +Pi-hole is a network-wide ad blocker that acts as a DNS sinkhole, blocking advertisements and tracking domains at the network level. It provides DNS-based ad blocking, DHCP server capabilities, and comprehensive network statistics. + +===== Overview ===== + +**Purpose:** Network-wide ad blocking and DNS +**URL:** http://pihole.yourdomain.duckdns.org (HTTP only) +**Authentication:** Authelia SSO protected +**Deployment:** Infrastructure stack +**Protocol:** DNS (port 53), DHCP (optional) + +===== Key Features ===== + +**Ad Blocking:** + * **DNS Sinkhole**: Blocks ad/tracking domains + * **Network Wide**: Protects all devices on network + * **Custom Lists**: Support for custom blocklists + * **Whitelist/Blacklist**: Fine-grained control + +**DNS Services:** + * **Recursive DNS**: Full DNS resolution + * **DNSSEC**: DNS security extensions + * **Conditional Forwarding**: Local hostname resolution + * **Rate Limiting**: Query rate limiting + +**DHCP Server:** + * **IP Address Assignment**: Dynamic IP allocation + * **Static Leases**: Reserved IP addresses + * **Network Configuration**: Gateway and DNS settings + * **Client Management**: Device tracking + +===== Configuration ===== + +**Container Configuration:** +```yaml +services: + pihole: + image: pihole/pihole:latest + container_name: pihole + restart: unless-stopped + environment: + - TZ=${TZ} + - WEBPASSWORD=${PIHOLE_PASSWORD} + - PIHOLE_DNS_=1.1.1.1;1.0.0.1;8.8.8.8;8.8.4.4 + - DHCP_ACTIVE=false # Set to true to enable DHCP + - DHCP_START=192.168.1.100 + - DHCP_END=192.168.1.200 + - DHCP_ROUTER=192.168.1.1 + - DHCP_LEASETIME=24 + volumes: + - ./pihole/etc-pihole:/etc/pihole + - ./pihole/etc-dnsmasq.d:/etc/dnsmasq.d + ports: + - 53:53/tcp + - 53:53/udp + - 8082:80/tcp # Web interface + networks: + - traefik-network + deploy: + resources: + limits: + cpus: '0.5' + memory: 256M + reservations: + cpus: '0.1' + memory: 64M + labels: + - "traefik.enable=true" + - "traefik.http.routers.pihole.rule=Host(`pihole.${DOMAIN}`)" + - "traefik.http.routers.pihole.entrypoints=websecure" + - "traefik.http.routers.pihole.tls.certresolver=letsencrypt" + - "traefik.http.routers.pihole.middlewares=authelia@docker" + - "traefik.http.services.pihole.loadbalancer.server.port=80" + - "x-dockge.url=http://pihole.${DOMAIN}" + dns: + - 127.0.0.1 + - 1.1.1.1 +``` + +**Environment Variables:** +```bash +# Required +PIHOLE_PASSWORD=your-secure-password + +# Optional DNS servers (comma-separated) +PIHOLE_DNS_=1.1.1.1;1.0.0.1;8.8.8.8;8.8.4.4 + +# DHCP Configuration (if enabled) +DHCP_ACTIVE=true +DHCP_START=192.168.1.100 +DHCP_END=192.168.1.200 +DHCP_ROUTER=192.168.1.1 +DHCP_LEASETIME=24 +``` + +===== DNS Configuration ===== + +**Upstream DNS Servers:** + * **Cloudflare**: 1.1.1.1, 1.0.0.1 (default) + * **Google**: 8.8.8.8, 8.8.4.4 + * **Quad9**: 9.9.9.9, 149.112.112.112 + * **OpenDNS**: 208.67.222.222, 208.67.220.220 + +**DNS Settings:** +```bash +# In Pi-hole admin interface +# Settings > DNS +# Enable DNSSEC for enhanced security +# Configure conditional forwarding for local network +``` + +**Client Configuration:** + * **Router DNS**: Set router to use Pi-hole IP + * **Device DNS**: Configure individual devices + * **DHCP**: Enable DHCP server in Pi-hole + * **IPv6**: Configure IPv6 DNS if needed + +===== Ad Blocking Setup ===== + +**Blocklists:** + * **Default Lists**: Pre-configured ad/tracking lists + * **Custom Lists**: Add your own blocklists + * **Gravity Update**: Regular list updates + * **Regex Filtering**: Advanced pattern matching + +**Whitelist/Blacklist:** + * **Whitelist**: Allow specific domains + * **Blacklist**: Block additional domains + * **Regex**: Pattern-based filtering + * **Client Groups**: Per-device rules + +**Group Management:** +```bash +# Create client groups for different policies +# Assign devices to groups +# Apply different filtering rules per group +``` + +===== DHCP Server Configuration ===== + +**DHCP Setup:** +```yaml +environment: + - DHCP_ACTIVE=true + - DHCP_START=192.168.1.100 + - DHCP_END=192.168.1.200 + - DHCP_ROUTER=192.168.1.1 + - DHCP_LEASETIME=24 +``` + +**Static Leases:** + * **MAC Address**: Device hardware address + * **IP Address**: Reserved static IP + * **Hostname**: Device name + * **Description**: Device description + +**DHCP Options:** + * **Domain Name**: Local domain suffix + * **NTP Servers**: Time synchronization + * **PXE Boot**: Network boot options + * **Vendor Options**: Device-specific options + +===== Monitoring & Statistics ===== + +**Dashboard Overview:** + * **Total Queries**: DNS query volume + * **Blocked Domains**: Ad blocking statistics + * **Top Clients**: Most active devices + * **Top Domains**: Frequently queried domains + +**Query Log:** + * **Real-time Monitoring**: Live query feed + * **Filtering**: Search and filter queries + * **Blocking Status**: See what's blocked/allowed + * **Client Tracking**: Per-device statistics + +**Long-term Statistics:** + * **Historical Data**: Query trends over time + * **Blocking Efficiency**: Ad blocking performance + * **Client Usage**: Device activity patterns + * **Domain Analysis**: Popular domain tracking + +===== Security Features ===== + +**Access Control:** + * **Web Interface**: Password protected + * **Authelia Integration**: SSO authentication + * **IP Restrictions**: Limit admin access + * **Session Management**: Secure login sessions + +**DNS Security:** + * **DNSSEC**: Domain signature validation + * **Query Logging**: Audit trail of requests + * **Rate Limiting**: Prevent DNS amplification + * **Cache Poisoning**: Protection against attacks + +**Network Security:** + * **Firewall Integration**: UFW/iptables rules + * **Port Protection**: Restrict unnecessary ports + * **Traffic Monitoring**: Network traffic analysis + * **Intrusion Detection**: Suspicious activity alerts + +===== Performance Optimization ===== + +**DNS Performance:** +```yaml +# Optimize DNS settings +# Settings > DNS > Interface Settings +# Enable cache optimization +# Configure upstream server timeout +``` + +**Resource Limits:** +```yaml +deploy: + resources: + limits: + cpus: '0.5' + memory: 256M + reservations: + cpus: '0.1' + memory: 64M +``` + +**Caching:** + * **DNS Cache**: Local query caching + * **Blocklist Cache**: Efficient blocklist lookups + * **Negative Cache**: Failed query caching + * **TTL Management**: Cache expiration handling + +===== Troubleshooting ===== + +**DNS Resolution Issues:** +```bash +# Check DNS resolution +nslookup google.com 127.0.0.1 + +# Test Pi-hole DNS +dig @127.0.0.1 google.com + +# Check upstream connectivity +dig @8.8.8.8 google.com +``` + +**Ad Blocking Problems:** + * **Test Blocking**: Visit ad-heavy sites + * **Check Lists**: Verify blocklists are updating + * **Whitelist Issues**: Check whitelist configuration + * **Client Bypass**: Some apps bypass DNS + +**DHCP Issues:** + * **IP Conflicts**: Check for IP address conflicts + * **Lease Problems**: Clear DHCP leases + * **Router Settings**: Verify router DHCP disabled + * **Network Issues**: Check network connectivity + +**Web Interface Problems:** + * **Login Issues**: Reset admin password + * **SSL Problems**: Check certificate validity + * **Authelia**: Verify SSO configuration + * **Browser Cache**: Clear browser cache + +**Troubleshooting Steps:** + 1. **Check logs**: `docker logs pihole` + 2. **Test DNS**: Verify DNS resolution works + 3. **Check configuration**: Validate environment variables + 4. **Network connectivity**: Test upstream DNS + 5. **Restart service**: `docker restart pihole` + +===== Advanced Configuration ===== + +**Custom DNS Records:** +```bash +# Add local DNS records +# Settings > Local DNS > DNS Records +# Add A, AAAA, CNAME, PTR records +``` + +**Conditional Forwarding:** +```bash +# Forward local queries to router +# Settings > DNS > Advanced Settings +# Enable conditional forwarding +# Set router IP and local domain +``` + +**Regex Blocking:** +```bash +# Advanced blocking patterns +# Settings > DNS > Group Management +# Create regex filters for complex patterns +``` + +**API Access:** +```bash +# Enable API for external tools +# Settings > API > Show API token +# Use token for programmatic access +``` + +===== Integration with Other Services ===== + +**Router Integration:** + * **DNS Settings**: Configure router to use Pi-hole + * **DHCP Disable**: Disable router DHCP if using Pi-hole + * **Port Forwarding**: Forward port 53 to Pi-hole + * **Static IP**: Give Pi-hole static IP address + +**Monitoring Integration:** + * **Prometheus**: Export metrics for monitoring + * **Grafana**: Create dashboards for Pi-hole stats + * **Uptime Kuma**: Monitor Pi-hole availability + * **Alerting**: Set up alerts for service issues + +**Backup Integration:** + * **Configuration Backup**: Backup Pi-hole settings + * **Blocklist Backup**: Save custom lists + * **DHCP Backup**: Backup DHCP leases + * **Automated Backups**: Schedule regular backups + +===== Best Practices ===== + +**DNS Configuration:** + * **Multiple Upstream**: Use multiple DNS servers + * **DNSSEC**: Enable DNS security + * **Conditional Forwarding**: Enable for local network + * **Rate Limiting**: Prevent abuse + +**Ad Blocking:** + * **Regular Updates**: Keep blocklists current + * **Custom Lists**: Add domain-specific blocks + * **Whitelist Carefully**: Only whitelist necessary sites + * **Test Blocking**: Verify blocking effectiveness + +**DHCP Management:** + * **IP Planning**: Plan IP address ranges + * **Static Leases**: Reserve IPs for servers + * **Lease Time**: Appropriate lease durations + * **Monitoring**: Track DHCP usage + +**Security:** + * **Strong Password**: Secure admin password + * **Access Control**: Limit admin access + * **Updates**: Keep Pi-hole updated + * **Monitoring**: Monitor for security issues + +**Maintenance:** + * **Log Rotation**: Manage log file sizes + * **Database Optimization**: Regular database maintenance + * **Backup Routine**: Regular configuration backups + * **Performance Monitoring**: Track resource usage + +===== Common Use Cases ===== + +**Home Network:** + * **Ad Blocking**: Block ads on all devices + * **Parental Controls**: Block inappropriate content + * **Device Management**: Track and manage devices + * **Network Monitoring**: Monitor network activity + +**Small Office:** + * **Content Filtering**: Block productivity-draining sites + * **Guest Network**: Separate guest DNS + * **Device Control**: Manage corporate devices + * **Reporting**: Generate usage reports + +**Development:** + * **Local DNS**: Resolve development domains + * **Testing**: Test ad blocking effectiveness + * **Network Simulation**: Simulate network conditions + * **Debugging**: Debug DNS-related issues + +Pi-hole provides essential network services with powerful ad blocking capabilities, serving as the DNS backbone of your homelab network. + +**Next:** Learn about [[services:infrastructure:dozzle|Dozzle]] or explore [[architecture:networking|Network Architecture]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/infrastructure/watchtower.txt b/config-templates/dokuwiki/data/pages/services/infrastructure/watchtower.txt new file mode 100644 index 0000000..4acfdfa --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/infrastructure/watchtower.txt @@ -0,0 +1,404 @@ +====== Watchtower ====== + +Watchtower is an automated container update service that monitors running Docker containers and automatically updates them when new images are available. It ensures your homelab services stay up-to-date with the latest security patches and features. + +===== Overview ===== + +**Purpose:** Automated container updates +**Deployment:** Infrastructure stack (currently disabled) +**Monitoring:** Passive background service +**Update Strategy:** Rolling updates with health checks + +===== Key Features ===== + +**Automated Updates:** + * **Image Monitoring**: Checks for new image versions + * **Scheduled Updates**: Configurable update intervals + * **Rolling Updates**: Updates containers one by one + * **Health Checks**: Waits for container health before proceeding + +**Update Control:** + * **Include/Exclude**: Control which containers to update + * **Update Notifications**: Email/Slack notifications + * **Rollback Support**: Revert to previous versions + * **Dry Run Mode**: Test updates without applying + +**Safety Features:** + * **Health Monitoring**: Ensures containers start successfully + * **Timeout Control**: Prevents hanging updates + * **Resource Limits**: Controls update resource usage + * **Backup Integration**: Coordinates with backup services + +===== Configuration ===== + +**Container Configuration:** +```yaml +services: + watchtower: + image: containrrr/watchtower:latest + container_name: watchtower + restart: unless-stopped + environment: + - WATCHTOWER_CLEANUP=true + - WATCHTOWER_POLL_INTERVAL=3600 + - WATCHTOWER_TIMEOUT=30s + - WATCHTOWER_NOTIFICATIONS=shoutrrr + - WATCHTOWER_NOTIFICATION_URL=discord://token@webhook + - WATCHTOWER_INCLUDE_STOPPED=false + - WATCHTOWER_REVIVE_STOPPED=false + - WATCHTOWER_REMOVE_VOLUMES=false + - WATCHTOWER_LABEL_ENABLE=true + - WATCHTOWER_MONITOR_ONLY=false + - WATCHTOWER_RUN_ONCE=false + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + command: --interval 3600 --cleanup --label-enable + deploy: + resources: + limits: + cpus: '0.2' + memory: 64M + reservations: + cpus: '0.01' + memory: 16M +``` + +**Environment Variables:** +```bash +# Update interval (seconds) +WATCHTOWER_POLL_INTERVAL=3600 + +# Update timeout +WATCHTOWER_TIMEOUT=30s + +# Cleanup old images +WATCHTOWER_CLEANUP=true + +# Notification settings +WATCHTOWER_NOTIFICATIONS=shoutrrr +WATCHTOWER_NOTIFICATION_URL=discord://token@webhook + +# Container control +WATCHTOWER_INCLUDE_STOPPED=false +WATCHTOWER_REVIVE_STOPPED=false +WATCHTOWER_REMOVE_VOLUMES=false + +# Label-based control +WATCHTOWER_LABEL_ENABLE=true + +# Monitoring mode +WATCHTOWER_MONITOR_ONLY=false + +# One-time run +WATCHTOWER_RUN_ONCE=false +``` + +===== Update Process ===== + +**Monitoring Phase:** + 1. **Image Check**: Queries Docker registry for new versions + 2. **Version Comparison**: Compares current vs latest versions + 3. **Update Decision**: Determines if update is needed + 4. **Schedule Planning**: Plans update timing + +**Update Execution:** + 1. **Container Stop**: Gracefully stops current container + 2. **Image Pull**: Downloads new image version + 3. **Container Start**: Starts container with new image + 4. **Health Check**: Verifies container health + 5. **Cleanup**: Removes old images (if enabled) + +**Post-Update:** + * **Notification**: Sends update notifications + * **Logging**: Records update details + * **Monitoring**: Continues monitoring for next updates + * **Error Handling**: Handles update failures + +===== Container Selection ===== + +**Label-Based Control:** +```yaml +# Enable updates for specific containers +labels: + - "com.centurylinklabs.watchtower.enable=true" + +# Disable updates for specific containers +labels: + - "com.centurylinklabs.watchtower.enable=false" +``` + +**Include/Exclude Patterns:** +```bash +# Include only specific containers +command: --include=traefik,authelia,dockge + +# Exclude specific containers +command: --exclude=plex,jellyfin + +# Use regex patterns +command: --include="^media-.*" +``` + +**Scope Control:** + * **All Containers**: Update all running containers + * **Specific Services**: Update only selected services + * **Stack-Based**: Update containers in specific stacks + * **Label-Based**: Use Docker labels for control + +===== Notification System ===== + +**Supported Notifications:** + * **Email**: SMTP email notifications + * **Slack**: Slack channel notifications + * **Discord**: Discord webhook notifications + * **Gotify**: Gotify push notifications + * **Telegram**: Telegram bot notifications + +**Notification Configuration:** +```yaml +environment: + - WATCHTOWER_NOTIFICATIONS=shoutrrr + - WATCHTOWER_NOTIFICATION_URL=slack://token@channel + # Or for Discord + - WATCHTOWER_NOTIFICATION_URL=discord://token@webhook + # Or for email + - WATCHTOWER_NOTIFICATION_URL=smtp://user:pass@host:port +``` + +**Notification Content:** + * **Update Started**: Container update beginning + * **Update Completed**: Successful update confirmation + * **Update Failed**: Error details and troubleshooting + * **Rollback Performed**: Automatic rollback notifications + +===== Safety & Reliability ===== + +**Health Checks:** +```yaml +# Wait for health checks +command: --interval 3600 --cleanup --label-enable --enable-healthchecks +``` + +**Timeout Management:** +```yaml +# Set update timeouts +environment: + - WATCHTOWER_TIMEOUT=60s +``` + +**Rollback Capability:** +```yaml +# Enable automatic rollback on failure +command: --rollback-on-failure +``` + +**Resource Protection:** + * **CPU Limits**: Prevent update resource exhaustion + * **Memory Limits**: Control memory usage during updates + * **Network Limits**: Manage download bandwidth + * **Concurrent Updates**: Limit simultaneous updates + +===== Scheduling ===== + +**Update Intervals:** +```bash +# Check every hour +command: --interval 3600 + +# Check every 24 hours +command: --interval 86400 + +# Check at specific times +command: --schedule "0 0 4 * * *" # Daily at 4 AM +``` + +**Maintenance Windows:** + * **Off-hours Updates**: Schedule updates during low-usage times + * **Weekend Updates**: Perform updates on weekends + * **Manual Control**: Trigger updates manually when needed + * **Holiday Scheduling**: Avoid updates during holidays + +===== Troubleshooting ===== + +**Update Failures:** +```bash +# Check Watchtower logs +docker logs watchtower + +# Manual update test +docker pull image:latest +docker stop container +docker rm container +docker run -d --name container image:latest +``` + +**Permission Issues:** + * **Docker Socket**: Verify socket access permissions + * **Registry Access**: Check Docker registry authentication + * **Network Issues**: Verify internet connectivity + * **Disk Space**: Ensure sufficient space for image downloads + +**Notification Problems:** + * **Webhook URLs**: Verify notification endpoint URLs + * **Authentication**: Check API tokens and credentials + * **Network Access**: Ensure outbound connectivity + * **Rate Limits**: Check service rate limiting + +**Performance Issues:** + * **Resource Usage**: Monitor CPU/memory during updates + * **Update Frequency**: Adjust polling intervals + * **Concurrent Updates**: Limit simultaneous container updates + * **Network Bandwidth**: Control download speeds + +**Troubleshooting Steps:** + 1. **Check logs**: `docker logs watchtower` + 2. **Test manually**: Perform manual container updates + 3. **Verify configuration**: Check environment variables + 4. **Test notifications**: Send test notifications + 5. **Restart service**: `docker restart watchtower` + +===== Advanced Configuration ===== + +**Custom Update Logic:** +```bash +# Use custom update script +command: --script /path/to/update-script.sh +``` + +**Lifecycle Hooks:** +```yaml +# Pre/post update hooks +command: --pre-check /path/to/pre-check.sh --post-check /path/to/post-check.sh +``` + +**Advanced Filtering:** +```bash +# Complex filtering rules +command: --filter-by-label=com.example.version=latest --filter-by-label=com.example.tier=frontend +``` + +**Monitoring Integration:** +```yaml +# Export metrics +command: --metrics +environment: + - WATCHTOWER_METRICS_PORT=8080 +``` + +===== Security Considerations ===== + +**Access Control:** + * **Docker Socket Security**: Read-only socket access + * **Registry Authentication**: Secure registry credentials + * **Network Security**: Secure update traffic + * **Audit Logging**: Track all update activities + +**Update Security:** + * **Image Verification**: Verify image authenticity + * **Vulnerability Scanning**: Check for security issues + * **Trusted Sources**: Only update from trusted registries + * **Rollback Security**: Secure rollback procedures + +===== Integration with Backup ===== + +**Backup Coordination:** +```yaml +# Coordinate with backup services +command: --pre-check /scripts/backup-check.sh --post-check /scripts/backup-verify.sh +``` + +**Backup Scripts:** +```bash +#!/bin/bash +# Pre-update backup +docker exec backup-service backup-now + +# Post-update verification +docker exec backup-service verify-backup +``` + +**Automated Backup:** + * **Pre-update Backup**: Backup before each update + * **Post-update Verification**: Verify backup integrity + * **Rollback Backup**: Maintain rollback capability + * **Retention Policy**: Manage backup retention + +===== Best Practices ===== + +**Update Strategy:** + * **Staged Updates**: Update non-critical services first + * **Monitoring**: Monitor updates closely initially + * **Testing**: Test updates in development first + * **Documentation**: Document update procedures + +**Safety Measures:** + * **Health Checks**: Always enable health checks + * **Timeouts**: Set appropriate update timeouts + * **Notifications**: Enable comprehensive notifications + * **Rollback**: Have rollback procedures ready + +**Performance:** + * **Resource Limits**: Appropriate CPU/memory limits + * **Update Windows**: Schedule during low-usage times + * **Concurrent Limits**: Limit simultaneous updates + * **Network Management**: Control bandwidth usage + +**Monitoring:** + * **Update Tracking**: Monitor update success/failure + * **Performance Impact**: Track update performance impact + * **Error Analysis**: Analyze update failure patterns + * **Success Metrics**: Track update success rates + +===== Use Cases ===== + +**Production Environments:** + * **Security Updates**: Automatic security patch deployment + * **Feature Updates**: Deploy new features automatically + * **Compliance**: Maintain compliance with update policies + * **Stability**: Ensure service stability through updates + +**Development Environments:** + * **Testing Updates**: Test update procedures safely + * **CI/CD Integration**: Integrate with development pipelines + * **Version Control**: Manage container versions + * **Rollback Testing**: Test rollback capabilities + +**Homelab Management:** + * **Convenience**: Hands-off update management + * **Security**: Maintain security through updates + * **Stability**: Prevent version drift issues + * **Monitoring**: Track update status and health + +**Enterprise Deployments:** + * **Policy Compliance**: Enforce update policies + * **Change Management**: Manage change through updates + * **Audit Trails**: Maintain update audit logs + * **Reporting**: Generate update compliance reports + +===== Manual Update Process ===== + +**When Watchtower is Disabled:** +```bash +# Manual update procedure +# 1. Identify containers to update +docker ps --format "table {{.Names}}\t{{.Image}}" + +# 2. Check for updates +docker pull image:latest + +# 3. Backup current state +docker tag current-image backup-image + +# 4. Stop and update container +docker stop container +docker rm container +docker run -d --name container image:latest + +# 5. Verify update +docker logs container +docker ps | grep container +``` + +Watchtower provides automated container updates with safety features and monitoring, ensuring your homelab services remain current and secure. + +**Next:** Learn about [[services:infrastructure:code-server|Code Server]] or explore [[architecture:backup|Backup Architecture]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/media/calibre-web.txt b/config-templates/dokuwiki/data/pages/services/media/calibre-web.txt new file mode 100644 index 0000000..ce4005b --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/media/calibre-web.txt @@ -0,0 +1,393 @@ +====== Calibre-Web ====== + +Calibre-Web is a web application that provides a clean web interface for browsing, reading, and downloading eBooks stored in a Calibre database. It allows you to access your eBook library from any device with a web browser. + +===== Overview ===== + +**Purpose:** Web interface for Calibre eBook library +**URL:** https://calibre.yourdomain.duckdns.org +**Authentication:** Built-in user management +**Deployment:** Media stack +**Database:** SQLite (Calibre database) + +===== Key Features ===== + +**Library Management:** + * **Browse Books**: Browse your eBook collection + * **Search & Filter**: Advanced search and filtering + * **Categories**: Organize by author, genre, series + * **Metadata Display**: Rich book information display + +**Reading Features:** + * **Online Reading**: Read books directly in browser + * **Download Options**: Download in multiple formats + * **Reading Progress**: Track reading progress + * **Bookmarks**: Save reading positions + +**User Management:** + * **Multiple Users**: Separate accounts for users + * **Access Control**: Configure user permissions + * **Reading Statistics**: Track reading habits + * **Personal Shelves**: Create custom book collections + +===== Configuration ===== + +**Container Configuration:** +```yaml +services: + calibre-web: + image: lscr.io/linuxserver/calibre-web:latest + container_name: calibre-web + restart: unless-stopped + environment: + - PUID=1000 + - PGID=1000 + - TZ=${TZ} + - DOCKER_MODS=linuxserver/mods:universal-calibre # Calibre integration + volumes: + - ./calibre-web/config:/config + - /mnt/media/books:/books # Calibre library location + networks: + - traefik-network + deploy: + resources: + limits: + cpus: '1.0' + memory: 512M + reservations: + cpus: '0.2' + memory: 128M + labels: + - "traefik.enable=true" + - "traefik.http.routers.calibre-web.rule=Host(`calibre.${DOMAIN}`)" + - "traefik.http.routers.calibre-web.entrypoints=websecure" + - "traefik.http.routers.calibre-web.tls.certresolver=letsencrypt" + - "traefik.http.routers.calibre-web.middlewares=authelia@docker" + - "traefik.http.services.calibre-web.loadbalancer.server.port=8083" + - "x-dockge.url=https://calibre.${DOMAIN}" +``` + +**Environment Variables:** +```bash +# User permissions +PUID=1000 +PGID=1000 + +# Timezone +TZ=America/New_York + +# Calibre integration (optional) +DOCKER_MODS=linuxserver/mods:universal-calibre +``` + +===== Calibre Database Setup ===== + +**Calibre Library Structure:** +``` +/mnt/media/books/ +├── metadata.db # Calibre database +├── metadata_db_prefs_backup.json +├── books/ # Book files +│ ├── Author Name/ +│ │ ├── Book Title (Year)/ +│ │ │ ├── book.epub +│ │ │ ├── cover.jpg +│ │ │ └── metadata.opf +│ └── Another Author/ +└── covers/ # Cover images +``` + +**Database Connection:** + * **Path**: `/books` (mounted Calibre library) + * **Auto-Detection**: Automatically finds metadata.db + * **Metadata Access**: Full access to Calibre metadata + * **Cover Images**: Access to book covers + +**Initial Setup:** + 1. **Place Calibre Library**: Mount existing Calibre library + 2. **Database Detection**: Calibre-Web finds metadata.db + 3. **Admin Account**: Create administrator account + 4. **Library Scan**: Scan and index books + +===== User Management ===== + +**Administrator Setup:** + 1. **First Access**: Visit Calibre-Web URL + 2. **Create Admin**: Set up administrator account + 3. **Configure Library**: Point to Calibre database + 4. **User Settings**: Configure application settings + +**User Accounts:** + * **User Creation**: Add user accounts + * **Permission Levels**: Admin, User, Guest + * **Library Access**: Control book access per user + * **Download Rights**: Configure download permissions + +**Authentication:** + * **Username/Password**: Standard authentication + * **LDAP Integration**: External user directory (optional) + * **Guest Access**: Allow anonymous browsing + * **Session Management**: Configurable session timeouts + +===== Library Features ===== + +**Browse & Search:** + * **Book Grid/List**: Multiple viewing modes + * **Advanced Search**: Search by title, author, genre + * **Filters**: Filter by language, format, rating + * **Sorting**: Sort by various criteria + +**Book Details:** + * **Metadata Display**: Title, author, description + * **Cover Images**: High-quality book covers + * **File Information**: Format, size, pages + * **Ratings & Reviews**: User ratings and reviews + +**Reading Interface:** + * **EPUB Reader**: Built-in EPUB reader + * **PDF Viewer**: PDF document viewer + * **Progress Tracking**: Reading progress saving + * **Bookmarking**: Save reading positions + +===== Download & Formats ===== + +**Supported Formats:** + * **EPUB**: Most common eBook format + * **PDF**: Portable document format + * **MOBI**: Kindle format + * **AZW3**: Amazon format + * **TXT**: Plain text + * **RTF**: Rich text format + +**Download Options:** + * **Direct Download**: Download original format + * **Format Conversion**: Convert to other formats + * **Bulk Download**: Download multiple books + * **ZIP Archives**: Download as compressed archives + +**Conversion Features:** + * **Calibre Integration**: Use Calibre for conversion + * **Format Support**: Convert between supported formats + * **Quality Settings**: Adjust conversion quality + * **Metadata Preservation**: Maintain book metadata + +===== Customization ===== + +**Interface Themes:** + * **Light Theme**: Clean, bright interface + * **Dark Theme**: Easy on the eyes + * **Custom CSS**: Advanced customization + * **Responsive Design**: Mobile-friendly interface + +**Language Support:** + * **Multiple Languages**: 20+ supported languages + * **Interface Translation**: Full UI translation + * **Metadata Languages**: Support for various languages + * **RTL Support**: Right-to-left language support + +**Display Options:** + * **Books per Page**: Configure pagination + * **Cover Sizes**: Adjust cover image sizes + * **Metadata Fields**: Customize displayed fields + * **Grid/List Views**: Choose viewing preferences + +===== Advanced Features ===== + +**Shelves & Collections:** + * **Custom Shelves**: Create personal book collections + * **Public Shelves**: Share collections with others + * **Smart Shelves**: Dynamic collections based on criteria + * **Shelf Management**: Organize and categorize shelves + +**Reading Statistics:** + * **Reading Progress**: Track reading progress + * **Reading Time**: Monitor reading duration + * **Books Read**: Track completed books + * **Reading Goals**: Set reading targets + +**Social Features:** + * **User Reviews**: Write and read book reviews + * **Ratings**: Rate books and see averages + * **Recommendations**: Book recommendation system + * **User Activity**: See what others are reading + +===== Integration Features ===== + +**Calibre Integration:** + * **Database Sync**: Sync with Calibre desktop + * **Metadata Updates**: Update from Calibre + * **Cover Downloads**: Download covers from Calibre + * **Format Conversion**: Use Calibre conversion tools + +**External Services:** + * **Goodreads**: Import ratings and reviews + * **Google Books**: Enhanced metadata + * **Open Library**: Additional book information + * **ISBN Lookup**: Automatic ISBN resolution + +**API Access:** + * **REST API**: Programmatic access + * **Webhook Support**: Event notifications + * **Third-party Integration**: Connect with other services + * **Automation**: Script-based automation + +===== Security Considerations ===== + +**Access Control:** + * **User Authentication**: Secure user authentication + * **Permission Levels**: Granular access control + * **IP Restrictions**: Limit access by IP address + * **Session Security**: Secure session management + +**Data Protection:** + * **File Permissions**: Proper file system permissions + * **Database Security**: SQLite database protection + * **Backup Security**: Secure backup procedures + * **Encryption**: Data encryption options + +===== Performance Optimization ===== + +**Resource Management:** +```yaml +deploy: + resources: + limits: + cpus: '1.0' + memory: 512M + reservations: + cpus: '0.2' + memory: 128M +``` + +**Database Optimization:** + * **Index Maintenance**: Regular database maintenance + * **Query Optimization**: Efficient database queries + * **Cache Management**: Metadata and cover caching + * **Search Optimization**: Fast search capabilities + +===== Troubleshooting ===== + +**Database Connection Issues:** +```bash +# Check database file permissions +ls -la /mnt/media/books/metadata.db + +# Verify database integrity +docker exec calibre-web sqlite3 /books/metadata.db ".tables" + +# Check Calibre-Web logs +docker logs calibre-web +``` + +**Book Display Problems:** + * **Cover Images**: Check cover file permissions + * **Metadata Issues**: Verify database integrity + * **File Permissions**: Check book file access + * **Format Support**: Verify supported formats + +**User Authentication Issues:** + * **Login Problems**: Check user credentials + * **Permission Errors**: Verify user permissions + * **Session Issues**: Clear browser cookies + * **Password Reset**: Administrator password reset + +**Reading Interface Issues:** + * **EPUB Display**: Check EPUB file validity + * **PDF Viewer**: Verify PDF compatibility + * **Progress Saving**: Check database write permissions + * **Bookmark Issues**: Clear browser cache + +**Troubleshooting Steps:** + 1. **Check logs**: `docker logs calibre-web` + 2. **Verify database**: Test database connectivity + 3. **Check permissions**: Validate file permissions + 4. **Test access**: Verify web interface access + 5. **Restart service**: `docker restart calibre-web` + +===== Backup & Recovery ===== + +**Configuration Backup:** +```bash +# Backup Calibre-Web configuration +docker run --rm \ + -v calibre-web-config:/config \ + -v $(pwd)/backup:/backup \ + busybox tar czf /backup/calibre-web-config.tar.gz /config +``` + +**Database Backup:** +```bash +# Backup Calibre database +docker run --rm \ + -v /mnt/media/books:/books \ + -v $(pwd)/backup:/backup \ + busybox tar czf /backup/calibre-library.tar.gz /books +``` + +**Recovery Process:** + 1. **Restore Configuration**: Restore config directory + 2. **Restore Database**: Restore Calibre library + 3. **Verify Integrity**: Check database and files + 4. **Update Permissions**: Fix file permissions + 5. **Test Access**: Verify web interface works + +===== Best Practices ===== + +**Library Management:** + * **Consistent Naming**: Follow Calibre naming conventions + * **Metadata Quality**: Maintain accurate metadata + * **File Organization**: Proper folder structure + * **Regular Backups**: Frequent library backups + +**User Management:** + * **Permission Planning**: Plan user access levels + * **Regular Audits**: Review user permissions + * **Password Policies**: Enforce strong passwords + * **Activity Monitoring**: Monitor user activity + +**Performance:** + * **Resource Allocation**: Appropriate CPU/memory limits + * **Database Maintenance**: Regular database optimization + * **Cache Management**: Optimize caching settings + * **Network Optimization**: Fast network access + +**Maintenance:** + * **Regular Updates**: Keep Calibre-Web updated + * **Database Maintenance**: Regular database cleanup + * **File System Checks**: Verify file integrity + * **Security Updates**: Apply security patches + +===== Advanced Configuration ===== + +**Reverse Proxy Configuration:** +```nginx +# Nginx configuration for additional features +location /calibre { + proxy_pass http://calibre-web:8083; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; +} +``` + +**LDAP Integration:** +```python +# LDAP configuration in config files +LDAP_URL = "ldap://your-ldap-server" +LDAP_USER_DN = "ou=users,dc=example,dc=com" +LDAP_GROUP_DN = "ou=groups,dc=example,dc=com" +``` + +**API Usage Examples:** +```bash +# Get library information +curl -u username:password https://calibre.yourdomain.duckdns.org/api/books + +# Search books +curl -u username:password "https://calibre.yourdomain.duckdns.org/api/books?search=author:smith" +``` + +Calibre-Web provides a beautiful, user-friendly web interface for your Calibre eBook library, making it easy to browse, read, and manage your digital book collection from any device. + +**Next:** Learn about [[services:media:qbittorrent|qBittorrent]] or explore [[architecture:backup|Backup Architecture]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/media/jellyfin.txt b/config-templates/dokuwiki/data/pages/services/media/jellyfin.txt new file mode 100644 index 0000000..22fbf43 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/media/jellyfin.txt @@ -0,0 +1,424 @@ +====== Jellyfin ====== + +Jellyfin is a free, open-source media server that allows you to organize, manage, and stream your personal media collection. It provides a modern, user-friendly interface for accessing movies, TV shows, music, and photos from any device. + +===== Overview ===== + +**Purpose:** Media server and streaming platform +**URL:** https://jellyfin.yourdomain.duckdns.org +**Authentication:** Built-in user management (no SSO) +**Deployment:** Media stack +**Features:** Multi-device streaming, transcoding, metadata management + +===== Key Features ===== + +**Media Management:** + * **Library Organization**: Automatic media organization + * **Metadata Fetching**: Rich metadata from online sources + * **Poster Art**: High-quality artwork and posters + * **Collections**: Custom media collections and playlists + +**Streaming Capabilities:** + * **Multi-Device Support**: Stream to any device + * **Adaptive Streaming**: Automatic quality adjustment + * **Transcoding**: Real-time video transcoding + * **Direct Play**: Direct streaming when supported + +**User Management:** + * **Multiple Users**: Separate accounts for family members + * **Parental Controls**: Content restrictions and ratings + * **Viewing History**: Track watched content + * **Personal Libraries**: User-specific content access + +===== Configuration ===== + +**Container Configuration:** +```yaml +services: + jellyfin: + image: lscr.io/linuxserver/jellyfin:latest + container_name: jellyfin + restart: unless-stopped + environment: + - PUID=1000 + - PGID=1000 + - TZ=${TZ} + - JELLYFIN_PublishedServerUrl=https://jellyfin.${DOMAIN} + volumes: + - ./jellyfin/config:/config + - /mnt/media/movies:/data/movies + - /mnt/media/tv:/data/tv + - /mnt/media/music:/data/music + - /mnt/transcode:/config/transcodes + devices: + - /dev/dri:/dev/dri # Hardware acceleration (optional) + networks: + - traefik-network + deploy: + resources: + limits: + cpus: '2.0' + memory: 2G + reservations: + cpus: '0.5' + memory: 512M + labels: + - "traefik.enable=true" + - "traefik.http.routers.jellyfin.rule=Host(`jellyfin.${DOMAIN}`)" + - "traefik.http.routers.jellyfin.entrypoints=websecure" + - "traefik.http.routers.jellyfin.tls.certresolver=letsencrypt" + # No Authelia middleware - direct access for app compatibility + - "traefik.http.services.jellyfin.loadbalancer.server.port=8096" + - "x-dockge.url=https://jellyfin.${DOMAIN}" +``` + +**Environment Variables:** +```bash +# User permissions +PUID=1000 +PGID=1000 + +# Timezone +TZ=America/New_York + +# Public URL (for external access) +JELLYFIN_PublishedServerUrl=https://jellyfin.yourdomain.duckdns.org +``` + +===== Media Library Setup ===== + +**Directory Structure:** +``` +/mnt/media/ +├── movies/ # Movie files +│ ├── Movie1 (2023)/ +│ └── Movie2 (2023)/ +├── tv/ # TV show files +│ ├── Show1/ +│ │ ├── Season 01/ +│ │ └── Season 02/ +│ └── Show2/ +├── music/ # Music files +│ ├── Artist1/ +│ └── Artist2/ +└── photos/ # Photo collections +``` + +**Library Configuration:** + * **Movie Library**: Point to `/data/movies` + * **TV Library**: Point to `/data/tv` + * **Music Library**: Point to `/data/music` + * **Photo Library**: Point to `/data/photos` + +**Naming Conventions:** +``` +Movies: "Movie Name (Year)/Movie Name (Year).mkv" +TV: "Show Name/Season 01/Show Name - S01E01.mkv" +Music: "Artist/Album/01 - Song Title.mp3" +``` + +===== Hardware Acceleration ===== + +**Intel Quick Sync:** +```yaml +devices: + - /dev/dri:/dev/dri + +environment: + - JELLYFIN_FFmpeg__probesize=1G + - JELLYFIN_FFmpeg__analyzeduration=200M +``` + +**NVIDIA GPU:** +```yaml +deploy: + resources: + reservations: + devices: + - driver: nvidia + count: 1 + capabilities: [gpu] + +environment: + - NVIDIA_VISIBLE_DEVICES=all + - NVIDIA_DRIVER_CAPABILITIES=all +``` + +**VAAPI (Software):** +```yaml +environment: + - JELLYFIN_FFmpeg__hwaccel=vaapi + - JELLYFIN_FFmpeg__hwaccel_device=/dev/dri/renderD128 + - JELLYFIN_FFmpeg__hwaccel_output_format=vaapi +``` + +===== User Management ===== + +**Administrator Setup:** + 1. **First Access**: Visit Jellyfin URL + 2. **Create Admin Account**: Set up administrator account + 3. **Configure Libraries**: Add media libraries + 4. **Set Preferences**: Configure server settings + +**User Accounts:** + * **User Creation**: Add family member accounts + * **Access Levels**: Configure library access per user + * **Parental Controls**: Set content ratings and restrictions + * **Device Limits**: Control simultaneous streams + +**Authentication:** + * **Local Users**: Username/password authentication + * **Easy PIN**: Simple PIN for quick access + * **Auto Login**: Remember login on trusted devices + +===== Transcoding Configuration ===== + +**Transcoding Settings:** +```yaml +# Transcode location +volumes: + - /mnt/transcode:/config/transcodes +``` + +**Quality Settings:** + * **Video Quality**: Adjust bitrate and resolution + * **Audio Quality**: Configure audio encoding + * **Container Format**: Choose output format + * **Hardware Acceleration**: Enable GPU transcoding + +**Performance Tuning:** + * **Concurrent Streams**: Limit simultaneous transcodes + * **Buffer Size**: Adjust transcoding buffer + * **Thread Count**: Configure encoding threads + * **Quality Presets**: Balance quality vs speed + +===== Metadata Management ===== + +**Metadata Sources:** + * **The Movie Database (TMDb)**: Movie and TV metadata + * **TheTVDB**: TV show information + * **MusicBrainz**: Music metadata + * **FanArt.tv**: Artwork and posters + +**Metadata Refresh:** + * **Automatic Updates**: Regular metadata updates + * **Manual Refresh**: Force metadata refresh + * **Image Downloads**: Download posters and artwork + * **Language Settings**: Configure metadata language + +**Custom Metadata:** + * **Override Information**: Manually edit metadata + * **Custom Images**: Upload custom artwork + * **Collections**: Create custom collections + * **Tags**: Add custom tags and genres + +===== Client Applications ===== + +**Official Apps:** + * **Android/iOS**: Mobile apps for streaming + * **Roku**: TV streaming device support + * **Fire TV**: Amazon Fire TV support + * **Android TV**: Android TV support + +**Third-Party Clients:** + * **Kodi**: Media center integration + * **Plex**: Alternative media server + * **Emby**: Similar media server + * **Infuse**: iOS/macOS media player + +**Web Client:** + * **Modern Interface**: Responsive web player + * **Keyboard Shortcuts**: Full keyboard navigation + * **Cast Support**: Chromecast and DLNA + * **Offline Sync**: Download for offline viewing + +===== Plugins & Extensions ===== + +**Official Plugins:** + * **Open Subtitles**: Subtitle downloading + * **MusicBrainz**: Enhanced music metadata + * **AniList**: Anime tracking integration + * **Trakt**: Watch history synchronization + +**Community Plugins:** + * **Kodi Sync**: Sync with Kodi library + * **FanArt**: Additional artwork sources + * **Theme Videos**: Movie theme videos + * **Trailer**: Trailer playback + +**Plugin Installation:** + 1. **Dashboard > Plugins**: Access plugin catalog + 2. **Browse Repository**: Find desired plugins + 3. **Install**: Click install button + 4. **Configure**: Set plugin preferences + +===== Backup & Recovery ===== + +**Configuration Backup:** +```bash +# Backup Jellyfin configuration +docker run --rm \ + -v jellyfin-config:/config \ + -v $(pwd)/backup:/backup \ + busybox tar czf /backup/jellyfin-config.tar.gz /config +``` + +**Database Backup:** +```bash +# Backup Jellyfin database +docker exec jellyfin sqlite3 /config/data/library.db .dump > jellyfin-backup.sql +``` + +**Media Backup:** + * **File System**: Backup media files separately + * **Metadata**: Configuration includes metadata + * **User Data**: User preferences and watch history + * **Plugins**: Plugin configurations + +===== Performance Optimization ===== + +**Resource Management:** +```yaml +deploy: + resources: + limits: + cpus: '2.0' + memory: 2G + reservations: + cpus: '0.5' + memory: 512M +``` + +**Optimization Tips:** + * **Library Scanning**: Schedule scans during off-hours + * **Transcoding Limits**: Limit concurrent transcodes + * **Cache Management**: Configure appropriate cache sizes + * **Network Optimization**: Use appropriate network settings + +===== Troubleshooting ===== + +**Playback Issues:** +```bash +# Check transcoding logs +docker logs jellyfin | grep -i ffmpeg + +# Verify hardware acceleration +docker exec jellyfin vainfo # VAAPI +docker exec jellyfin nvidia-smi # NVIDIA +``` + +**Library Scanning Problems:** + * **Permission Issues**: Check file permissions + * **Naming Problems**: Verify file naming conventions + * **Metadata Errors**: Check metadata provider status + * **Network Issues**: Verify internet connectivity + +**Web Interface Issues:** + * **Loading Problems**: Clear browser cache + * **SSL Errors**: Check certificate validity + * **CORS Issues**: Verify reverse proxy configuration + * **JavaScript Errors**: Check browser compatibility + +**Transcoding Issues:** + * **Hardware Acceleration**: Verify GPU access + * **Codec Support**: Check supported codecs + * **Resource Limits**: Monitor CPU/memory usage + * **Quality Settings**: Adjust transcoding parameters + +**Troubleshooting Steps:** + 1. **Check logs**: `docker logs jellyfin` + 2. **Verify configuration**: Check environment variables + 3. **Test access**: Verify web interface access + 4. **Check permissions**: Validate file permissions + 5. **Restart service**: `docker restart jellyfin` + +===== Security Considerations ===== + +**Access Control:** + * **User Authentication**: Strong password requirements + * **Network Security**: Restrict network access + * **HTTPS Only**: Force secure connections + * **Session Management**: Configure session timeouts + +**Media Security:** + * **File Permissions**: Proper file system permissions + * **Network Shares**: Secure network share access + * **Backup Security**: Encrypt backup data + * **Access Logging**: Monitor access patterns + +===== Integration with Media Stack ===== + +**Sonarr/Radarr Integration:** + * **Automatic Downloads**: Integration with download clients + * **Library Updates**: Automatic library refreshes + * **Quality Profiles**: Match download quality to playback + * **Naming Conventions**: Consistent file naming + +**qBittorrent Integration:** + * **Download Monitoring**: Track download progress + * **Category Management**: Organize downloads by type + * **Completion Notifications**: Notify when downloads complete + * **File Management**: Automatic file organization + +**Hardware Acceleration:** + * **GPU Utilization**: Leverage available GPU resources + * **Transcoding Efficiency**: Optimize transcoding performance + * **Power Management**: Balance performance and power usage + * **Resource Monitoring**: Monitor hardware utilization + +===== Best Practices ===== + +**Library Management:** + * **Consistent Naming**: Follow naming conventions + * **Quality Standards**: Maintain consistent quality + * **Metadata Accuracy**: Keep metadata up-to-date + * **Regular Maintenance**: Periodic library cleanup + +**Performance:** + * **Resource Allocation**: Appropriate CPU/memory limits + * **Transcoding Settings**: Balance quality and performance + * **Caching Strategy**: Optimize cache usage + * **Network Configuration**: Optimize network settings + +**User Experience:** + * **Interface Customization**: Customize user interfaces + * **Device Profiles**: Optimize for different devices + * **Subtitle Management**: Configure subtitle preferences + * **Audio Settings**: Configure audio preferences + +**Maintenance:** + * **Regular Updates**: Keep Jellyfin updated + * **Library Scans**: Regular library maintenance + * **Backup Routine**: Regular configuration backups + * **Performance Monitoring**: Monitor system performance + +===== Advanced Configuration ===== + +**Custom CSS:** +```css +/* Custom theme modifications */ +.dashboardHeader { + background-color: #your-color; +} + +.libraryCard { + border-radius: 10px; +} +``` + +**API Access:** +```bash +# Access Jellyfin API +curl -H "X-MediaBrowser-Token: your-api-key" \ + https://jellyfin.yourdomain.duckdns.org/Items +``` + +**Webhook Integration:** + * **Playback Events**: Trigger actions on media events + * **User Actions**: Monitor user activities + * **System Events**: Respond to system events + * **External Integration**: Connect with other services + +Jellyfin provides a powerful, free alternative to proprietary media servers, offering comprehensive media management and streaming capabilities with excellent client support across all platforms. + +**Next:** Learn about [[services:media:calibre-web|Calibre-Web]] or explore [[architecture:storage|Storage Architecture]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/media/qbittorrent.txt b/config-templates/dokuwiki/data/pages/services/media/qbittorrent.txt new file mode 100644 index 0000000..ce0f7f5 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/media/qbittorrent.txt @@ -0,0 +1,391 @@ +====== qBittorrent ====== + +qBittorrent is a free and open-source BitTorrent client that provides a web-based interface for downloading and managing torrent files. In the AI-Homelab, it's configured to route all traffic through Gluetun VPN for enhanced privacy and security. + +===== Overview ===== + +**Purpose:** Torrent downloading with VPN protection +**URL:** https://qbit.yourdomain.duckdns.org +**Authentication:** Built-in web UI authentication +**Deployment:** Media stack (VPN-routed through Gluetun) +**VPN Integration:** Routes through Gluetun container + +===== Key Features ===== + +**Torrent Management:** + * **Web Interface**: Clean, responsive web UI + * **Torrent Creation**: Create torrents from files/folders + * **Magnet Links**: Support for magnet link downloads + * **Batch Downloads**: Download multiple torrents + * **RSS Feeds**: Automatic RSS feed monitoring + +**Download Control:** + * **Speed Limits**: Set download/upload speed limits + * **Bandwidth Management**: Per-torrent bandwidth allocation + * **Queue Management**: Priority-based download queuing + * **Auto-Management**: Automatic torrent management + +**Privacy & Security:** + * **VPN Routing**: All traffic through Gluetun VPN + * **IP Binding**: Bind to VPN interface only + * **Encryption**: Protocol encryption support + * **Proxy Support**: SOCKS5/HTTP proxy support + +===== Configuration ===== + +**Container Configuration:** +```yaml +services: + qbittorrent: + image: lscr.io/linuxserver/qbittorrent:latest + container_name: qbittorrent + network_mode: "service:gluetun" # Route through VPN + depends_on: + - gluetun + environment: + - PUID=1000 + - PGID=1000 + - TZ=${TZ} + - WEBUI_PORT=8080 + volumes: + - ./qbittorrent/config:/config + - /mnt/downloads:/downloads + restart: unless-stopped + deploy: + resources: + limits: + cpus: '2.0' + memory: 1G + reservations: + cpus: '0.5' + memory: 256M +``` + +**Gluetun Configuration (Update):** +```yaml +# In gluetun service, add port mapping +gluetun: + ports: + - 8080:8080 # qBittorrent WebUI + - 6881:6881 # Torrent ports (TCP) + - 6881:6881/udp # Torrent ports (UDP) +``` + +**Environment Variables:** +```bash +# User permissions +PUID=1000 +PGID=1000 + +# Timezone +TZ=America/New_York + +# Web UI port +WEBUI_PORT=8080 +``` + +===== VPN Integration ===== + +**Network Mode:** +```yaml +network_mode: "service:gluetun" +``` + +**Benefits:** + * **IP Protection**: All torrent traffic through VPN + * **ISP Protection**: Hide torrenting from ISP + * **Geographic Access**: Access geo-restricted content + * **Privacy**: Enhanced download privacy + +**Port Mapping:** + * **WebUI**: 8080 (internal to Gluetun) + * **Torrent TCP**: 6881 + * **Torrent UDP**: 6881 + +**VPN Verification:** +```bash +# Check if qBittorrent is using VPN IP +docker exec gluetun curl -s ifconfig.me + +# Verify qBittorrent is accessible through VPN +curl -k https://qbit.yourdomain.duckdns.org +``` + +===== Initial Setup ===== + +**First Access:** + 1. **Navigate**: Visit qBittorrent URL + 2. **Default Credentials**: admin/adminadmin + 3. **Change Password**: Immediately change default password + 4. **Configure Settings**: Set up download preferences + +**Basic Configuration:** + * **Download Location**: Set to `/downloads` + * **Temporary Files**: Configure temp directory + * **Auto-Management**: Enable automatic torrent management + * **WebUI Settings**: Configure interface preferences + +===== Download Management ===== + +**Adding Torrents:** + * **Torrent Files**: Upload .torrent files + * **Magnet Links**: Paste magnet links + * **URLs**: Add torrent URLs + * **Batch Operations**: Add multiple torrents + +**Download Categories:** + * **Category Creation**: Create download categories + * **Path Assignment**: Assign paths per category + * **Automatic Sorting**: Auto-assign categories + * **Category Management**: Organize downloads + +**Queue Management:** + * **Priority Setting**: Set download priorities + * **Queue Limits**: Limit concurrent downloads + * **Speed Allocation**: Allocate bandwidth per torrent + * **Sequential Downloads**: Download files in order + +===== Advanced Features ===== + +**RSS Integration:** + * **RSS Feeds**: Add RSS torrent feeds + * **Automatic Downloads**: Auto-download matching torrents + * **Filters**: Set download filters and rules + * **Smart Filtering**: Advanced filtering options + +**Search Integration:** + * **Built-in Search**: Search torrent sites + * **Search Plugins**: Install additional search plugins + * **Plugin Management**: Manage search engines + * **Search History**: Track search history + +**Automation:** + * **Watch Folders**: Monitor folders for new torrents + * **Auto-Tagging**: Automatic torrent tagging + * **Script Integration**: Execute scripts on completion + * **API Integration**: REST API for automation + +===== Performance Optimization ===== + +**Speed Settings:** +```yaml +# Recommended settings for VPN +Global maximum number of upload slots: 20 +Global maximum number of half-open connections: 500 +Maximum number of upload slots per torrent: 4 +Maximum number of connections per torrent: 100 +``` + +**Disk Settings:** + * **Disk Cache**: Set to 64-128 MB + * **Disk Cache Expiry**: 60 seconds + * **OS Cache**: Enable OS cache + * **Coalesce Reads**: Enable for SSDs + +**Connection Settings:** + * **Global Max Connections**: 500 + * **Max Per Torrent**: 100 + * **Max Upload Slots**: 20 + * **Max Half-Open**: 500 + +===== Security Configuration ===== + +**WebUI Security:** + * **Authentication**: Enable username/password + * **HTTPS**: Force HTTPS connections + * **IP Filtering**: Restrict access by IP + * **Session Timeout**: Configure session limits + +**Network Security:** + * **Encryption**: Enable protocol encryption + * **DHT**: Enable DHT for peer discovery + * **PEX**: Enable peer exchange + * **LSD**: Enable local service discovery + +**VPN Security:** + * **Kill Switch**: Gluetun provides kill switch + * **DNS Leak Protection**: VPN DNS protection + * **IPv6 Blocking**: Block IPv6 leaks + * **Port Forwarding**: VPN port forwarding + +===== Integration with Media Stack ===== + +**Sonarr/Radarr Integration:** +```yaml +# In Sonarr/Radarr settings +Download Client: qBittorrent +Host: qbittorrent # Container name +Port: 8080 +Username: your-username +Password: your-password +Category: sonarr # Use categories for organization +``` + +**Category Setup:** + * **sonarr**: For TV show downloads + * **radarr**: For movie downloads + * **manual**: For manual downloads + * **books**: For book downloads + +**Path Mapping:** + * **/downloads/complete/sonarr**: TV shows + * **/downloads/complete/radarr**: Movies + * **/downloads/complete/manual**: Manual downloads + +===== Monitoring & Maintenance ===== + +**Health Checks:** +```yaml +healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8080"] + interval: 30s + timeout: 10s + retries: 3 +``` + +**Log Monitoring:** +```bash +# View qBittorrent logs +docker logs qbittorrent + +# View Gluetun logs (VPN) +docker logs gluetun +``` + +**Performance Monitoring:** + * **Download Speed**: Monitor download/upload speeds + * **Connection Count**: Track peer connections + * **Disk I/O**: Monitor disk usage + * **Memory Usage**: Track memory consumption + +===== Troubleshooting ===== + +**VPN Connection Issues:** +```bash +# Check VPN status +docker exec gluetun sh -c "curl -s ifconfig.me" + +# Verify Gluetun is running +docker ps | grep gluetun + +# Check Gluetun logs +docker logs gluetun | grep -i wireguard +``` + +**WebUI Access Issues:** + * **Port Mapping**: Verify port 8080 is mapped in Gluetun + * **Network Mode**: Confirm `network_mode: "service:gluetun"` + * **Firewall**: Check firewall rules + * **Traefik**: Verify Traefik routing + +**Download Problems:** + * **Port Forwarding**: Check if VPN supports port forwarding + * **Speed Limits**: Remove artificial speed limits + * **Tracker Issues**: Check tracker status + * **Peer Connections**: Verify peer connectivity + +**Common Issues:** + * **No Downloads**: Check VPN connection and port forwarding + * **Slow Speeds**: Verify VPN server selection and speed + * **Connection Errors**: Check firewall and network settings + * **Authentication**: Verify username/password credentials + +**Troubleshooting Steps:** + 1. **Check VPN**: Verify Gluetun is connected + 2. **Test Access**: Access WebUI directly + 3. **Check Logs**: Review container logs + 4. **Verify Ports**: Confirm port mappings + 5. **Test Downloads**: Try a known working torrent + +===== Backup & Recovery ===== + +**Configuration Backup:** +```bash +# Backup qBittorrent configuration +docker run --rm \ + -v qbittorrent-config:/config \ + -v $(pwd)/backup:/backup \ + busybox tar czf /backup/qbittorrent-config.tar.gz /config +``` + +**Download Recovery:** + * **Resume Downloads**: qBittorrent auto-resumes + * **Torrent Files**: Backup .torrent files + * **Fast Resume**: Use fast resume data + * **Re-add Torrents**: Re-add from backup + +**Migration:** + 1. **Stop Container**: Stop qBittorrent + 2. **Backup Config**: Backup configuration directory + 3. **Restore Config**: Restore to new location + 4. **Update Paths**: Update download paths if changed + 5. **Start Container**: Restart qBittorrent + +===== Best Practices ===== + +**VPN Usage:** + * **Dedicated Server**: Use VPN server optimized for P2P + * **Port Forwarding**: Enable port forwarding when available + * **Kill Switch**: Always use VPN kill switch + * **IP Rotation**: Rotate VPN servers periodically + +**Download Management:** + * **Category Organization**: Use categories for organization + * **Speed Limits**: Set reasonable speed limits + * **Queue Management**: Limit concurrent downloads + * **Disk Space**: Monitor available disk space + +**Security:** + * **Strong Passwords**: Use strong WebUI passwords + * **IP Restrictions**: Limit WebUI access + * **Regular Updates**: Keep qBittorrent updated + * **VPN Always**: Never disable VPN routing + +**Performance:** + * **Resource Allocation**: Appropriate CPU/memory limits + * **Disk I/O**: Use fast storage for downloads + * **Network Optimization**: Optimize VPN server selection + * **Cache Settings**: Optimize disk cache settings + +===== Advanced Configuration ===== + +**qBittorrent.conf Settings:** +```ini +[Preferences] +WebUI\Username=your-username +WebUI\Password_PBKDF2="encrypted-password" +WebUI\Port=8080 +Downloads\SavePath=/downloads +Downloads\TempPath=/downloads/temp +``` + +**API Usage:** +```bash +# Get torrent list +curl -u username:password "http://localhost:8080/api/v2/torrents/info" + +# Add magnet link +curl -X POST \ + -u username:password \ + -d "urls=magnet:?..." \ + http://localhost:8080/api/v2/torrents/add +``` + +**Integration Scripts:** +```bash +#!/bin/bash +# Auto-organize completed downloads +QB_HOST="http://localhost:8080" +QB_USER="username" +QB_PASS="password" + +# Get completed torrents +completed=$(curl -s -u $QB_USER:$QB_PASS "$QB_HOST/api/v2/torrents/info?filter=completed") + +# Process completed torrents +# Add your organization logic here +``` + +qBittorrent provides a powerful, privacy-focused torrent downloading solution that integrates seamlessly with your media automation stack while maintaining security through VPN routing. + +**Next:** Explore [[services:media-management:start|Media Management Services]] or return to [[services:media:start|Media Services Overview]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/media/start.txt b/config-templates/dokuwiki/data/pages/services/media/start.txt new file mode 100644 index 0000000..d5945f2 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/media/start.txt @@ -0,0 +1,194 @@ +====== Media Services ====== + +The Media Services stack provides comprehensive media management, streaming, and downloading capabilities for your homelab. These services handle everything from media library organization to automated downloading and streaming. + +===== Overview ===== + +**Stack Components:** + * **[[services:media:jellyfin|Jellyfin]]**: Media server for streaming movies, TV shows, and music + * **[[services:media:calibre-web|Calibre-Web]]**: Web interface for eBook library management + * **[[services:media:qbittorrent|qBittorrent]]**: Torrent client with VPN protection + +**Key Features:** + * **Unified Media Access**: Stream media from any device + * **EBook Management**: Browse and read digital books + * **Secure Downloading**: VPN-protected torrent downloads + * **Cross-Platform**: Works on all devices and platforms + +===== Service Details ===== + +^ Service ^ Purpose ^ URL ^ Authentication ^ Storage ^ +| [[services:media:jellyfin|Jellyfin]] | Media streaming server | https://jellyfin.${DOMAIN} | Apps/devices | /mnt/media | +| [[services:media:calibre-web|Calibre-Web]] | eBook web interface | https://calibre.${DOMAIN} | Built-in users | /mnt/media/books | +| [[services:media:qbittorrent|qBittorrent]] | Torrent downloads | https://qbit.${DOMAIN} | Web UI auth | /mnt/downloads | + +===== Architecture ===== + +**Storage Layout:** +``` +/mnt/media/ +├── movies/ # Movie files +├── tv/ # TV show files +├── music/ # Music files +├── books/ # Calibre eBook library +│ ├── metadata.db +│ └── books/ +└── photos/ # Photo collections + +/mnt/downloads/ +├── complete/ # Completed downloads +├── incomplete/ # Active downloads +└── temp/ # Temporary files +``` + +**Network Configuration:** + * **Jellyfin**: Direct access (no SSO for app compatibility) + * **Calibre-Web**: Authelia SSO protection + * **qBittorrent**: Authelia SSO + VPN routing through Gluetun + +===== Deployment ===== + +**Docker Compose (media.yml):** +```yaml +services: + jellyfin: + image: lscr.io/linuxserver/jellyfin:latest + # ... Jellyfin configuration + + calibre-web: + image: lscr.io/linuxserver/calibre-web:latest + # ... Calibre-Web configuration + + qbittorrent: + image: lscr.io/linuxserver/qbittorrent:latest + network_mode: "service:gluetun" # VPN routing + # ... qBittorrent configuration +``` + +**Prerequisites:** + * **Core Stack**: Traefik, Authelia, Gluetun must be running + * **Storage**: /mnt/media and /mnt/downloads mounted + * **VPN**: Gluetun configured with torrent-friendly provider + * **Permissions**: Proper PUID/PGID for file access + +===== Integration ===== + +**With Media Management:** + * **Sonarr/Radarr**: Auto-download TV/movies + * **qBittorrent**: Download client for automation + * **Jellyfin**: Media library scanning and streaming + * **Prowlarr**: Indexer management + +**With Home Automation:** + * **Home Assistant**: Media control integration + * **Node-RED**: Custom media workflows + * **MotionEye**: Security camera integration + +**With Monitoring:** + * **Uptime Kuma**: Service availability monitoring + * **Grafana**: Performance dashboards + * **Prometheus**: Resource monitoring + +===== Security Considerations ===== + +**Access Control:** + * **Jellyfin**: No SSO (device/app compatibility) + * **Calibre-Web**: SSO protected + * **qBittorrent**: SSO protected + VPN isolation + +**Network Security:** + * **VPN Routing**: qBittorrent traffic through VPN + * **Firewall Rules**: Restrict external access + * **SSL/TLS**: All services use HTTPS + * **Authentication**: Strong passwords required + +===== Performance Optimization ===== + +**Hardware Acceleration:** + * **Jellyfin**: GPU transcoding support + * **Intel Quick Sync**: Hardware encoding/decoding + * **NVIDIA NVENC**: GPU-accelerated transcoding + * **VAAPI**: Linux video acceleration + +**Storage Optimization:** + * **SSD Storage**: Fast access for media files + * **RAID Arrays**: Data redundancy and performance + * **Network Storage**: NAS integration for large libraries + * **Caching**: Metadata and thumbnail caching + +**Resource Allocation:** +```yaml +# Recommended limits +jellyfin: + cpus: '2.0' + memory: 4G + +calibre-web: + cpus: '1.0' + memory: 512M + +qbittorrent: + cpus: '2.0' + memory: 1G +``` + +===== Maintenance ===== + +**Regular Tasks:** + * **Library Scans**: Regular media library scanning + * **Database Optimization**: Calibre database maintenance + * **Download Cleanup**: Remove completed torrents + * **Update Checks**: Keep services updated + +**Backup Strategy:** + * **Configuration**: Backup service configurations + * **Databases**: Backup Calibre and Jellyfin databases + * **Metadata**: Preserve media metadata + * **Automation**: Automated backup scripts + +===== Troubleshooting ===== + +**Common Issues:** + * **Media Not Showing**: Check file permissions and paths + * **Slow Streaming**: Verify transcoding settings + * **Download Issues**: Check VPN connection and ports + * **Authentication**: Verify SSO configuration + +**Diagnostic Commands:** +```bash +# Check service status +docker compose -f media.yml ps + +# View logs +docker compose -f media.yml logs -f service-name + +# Test VPN connection +docker exec gluetun curl -s ifconfig.me + +# Check file permissions +ls -la /mnt/media/ +``` + +===== Best Practices ===== + +**Library Organization:** + * **Consistent Naming**: Follow media naming conventions + * **Folder Structure**: Logical folder hierarchy + * **Metadata Quality**: Accurate media information + * **Regular Maintenance**: Keep libraries organized + +**Security:** + * **VPN Always**: Never disable VPN for downloads + * **Strong Passwords**: Use strong authentication + * **Access Logging**: Monitor access patterns + * **Regular Updates**: Keep services current + +**Performance:** + * **Resource Monitoring**: Track CPU/memory usage + * **Storage Optimization**: Use appropriate storage types + * **Network Optimization**: Fast network connections + * **Caching**: Enable appropriate caching + +The Media Services stack provides a complete media entertainment solution with streaming, eBook management, and secure downloading capabilities. + +**Next:** Explore [[services:media-management:start|Media Management Services]] for automated downloading or return to [[services:start|Services Overview]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/services/start.txt b/config-templates/dokuwiki/data/pages/services/start.txt new file mode 100644 index 0000000..6f1c552 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/services/start.txt @@ -0,0 +1,282 @@ +====== Services Overview ====== + +The AI-Homelab provides 70+ pre-configured services organized into logical stacks. All services follow consistent patterns for deployment, security, and management. + +===== Service Categories ===== + +| Category | Services | Description | Deployment | +|----------|----------|-------------|------------| +| **Core** | 4 services | Essential infrastructure | Automatic | +| **Infrastructure** | 8 services | Management and monitoring | Automatic | +| **Media** | 3 services | Media servers and downloaders | Manual | +| **Media Management** | 10 services | Download automation | Manual | +| **Productivity** | 8+6 services | Office and collaboration | Manual | +| **Home Automation** | 7 services | Smart home integration | Manual | +| **Monitoring** | 8 services | Observability and alerting | Manual | +| **Utilities** | 6 services | Backup and miscellaneous | Manual | +| **Development** | 6 services | Development tools | Manual | +| **Alternatives** | 6+3 services | Alternative implementations | Optional | + +===== Core Infrastructure ===== + +**Deployed automatically with setup scripts.** + +| Service | URL | Purpose | SSO | Documentation | +|---------|-----|---------|-----|---------------| +| **[[services:core:duckdns|DuckDNS]]** | - | Dynamic DNS updates | - | [[services:core:duckdns|Details]] | +| **[[services:core:traefik|Traefik]]** | `https://traefik.yourdomain.duckdns.org` | Reverse proxy | ✓ | [[services:core:traefik|Details]] | +| **[[services:core:authelia|Authelia]]** | `https://auth.yourdomain.duckdns.org` | SSO authentication | - | [[services:core:authelia|Details]] | +| **[[services:core:gluetun|Gluetun]]** | - | VPN client | - | [[services:core:gluetun|Details]] | +| **[[services:core:sablier|Sablier]]** | `http://sablier.yourdomain.duckdns.org:10000` | Lazy loading | - | [[services:core:sablier|Details]] | + +===== Infrastructure Services ===== + +**Management and monitoring tools.** + +| Service | URL | Purpose | SSO | Documentation | +|---------|-----|---------|-----|---------------| +| **[[services:infrastructure:dockge|Dockge]]** | `https://dockge.yourdomain.duckdns.org` | Stack manager | ✓ | [[services:infrastructure:dockge|Details]] | +| **[[services:infrastructure:pihole|Pi-hole]]** | `http://pihole.yourdomain.duckdns.org` | DNS & ad blocking | ✓ | [[services:infrastructure:pihole|Details]] | +| **[[services:infrastructure:dozzle|Dozzle]]** | `https://dozzle.yourdomain.duckdns.org` | Log viewer | ✓ | [[services:infrastructure:dozzle|Details]] | +| **[[services:infrastructure:glances|Glances]]** | `https://glances.yourdomain.duckdns.org` | System monitor | ✓ | [[services:infrastructure:glances|Details]] | +| **[[services:infrastructure:watchtower|Watchtower]]** | - | Auto updates | - | [[services:infrastructure:watchtower|Details]] | +| **[[services:infrastructure:code-server|Code Server]]** | `https://code.yourdomain.duckdns.org` | VS Code in browser | ✓ | [[services:infrastructure:code-server|Details]] | +| **[[services:infrastructure:docker-proxy|Docker Proxy]]** | - | Secure socket access | - | [[services:infrastructure:docker-proxy|Details]] | + +===== Media Services ===== + +**Media servers, eBook management, and secure downloading.** + +| Service | URL | Purpose | SSO | Documentation | +|---------|-----|---------|-----|---------------| +| **[[services:media:jellyfin|Jellyfin]]** | `https://jellyfin.yourdomain.duckdns.org` | Media streaming server | ✗ | [[services:media:jellyfin|Details]] | +| **[[services:media:calibre-web|Calibre-Web]]** | `https://calibre.yourdomain.duckdns.org` | eBook web interface | ✓ | [[services:media:calibre-web|Details]] | +| **[[services:media:qbittorrent|qBittorrent]]** | `https://qbit.yourdomain.duckdns.org` | Torrent client (VPN) | ✓ | [[services:media:qbittorrent|Details]] | + +===== Media Management ===== + +**Download automation and organization.** + +| Service | URL | Purpose | SSO | +|---------|-----|---------|-----| +| **Sonarr** | `https://sonarr.yourdomain.duckdns.org` | TV automation | ✓ | +| **Radarr** | `https://radarr.yourdomain.duckdns.org` | Movie automation | ✓ | +| **Prowlarr** | `https://prowlarr.yourdomain.duckdns.org` | Indexer manager | ✓ | +| **Readarr** | `https://readarr.yourdomain.duckdns.org` | Book automation | ✓ | +| **Lidarr** | `https://lidarr.yourdomain.duckdns.org` | Music automation | ✓ | +| **Lazy Librarian** | `https://lazylibrarian.yourdomain.duckdns.org` | Book manager | ✓ | +| **Mylar3** | `https://mylar.yourdomain.duckdns.org` | Comic manager | ✓ | +| **Jellyseerr** | `https://jellyseerr.yourdomain.duckdns.org` | Media requests | ✓ | +| **FlareSolverr** | - | Cloudflare bypass | - | +| **Tdarr Server** | `https://tdarr.yourdomain.duckdns.org` | Transcoding | ✓ | +| **Tdarr Node** | - | Transcoding worker | - | +| **Unmanic** | `https://unmanic.yourdomain.duckdns.org` | Library optimizer | ✓ | +| **Bazarr** | `https://bazarr.yourdomain.duckdns.org` | Subtitle manager | ✓ | + +===== Productivity Services ===== + +**Office, collaboration, and content management.** + +| Service | URL | Purpose | SSO | Database | +|---------|-----|---------|-----|----------| +| **Nextcloud** | `https://nextcloud.yourdomain.duckdns.org` | File sync | ✓ | MariaDB | +| **Mealie** | `https://mealie.yourdomain.duckdns.org` | Recipe manager | ✗ | - | +| **WordPress** | `https://blog.yourdomain.duckdns.org` | Blog platform | ✗ | MariaDB | +| **Gitea** | `https://git.yourdomain.duckdns.org` | Git service | ✓ | PostgreSQL | +| **DokuWiki** | `https://wiki.yourdomain.duckdns.org` | Documentation | ✓ | - | +| **BookStack** | `https://docs.yourdomain.duckdns.org` | Documentation | ✓ | MariaDB | +| **MediaWiki** | `https://mediawiki.yourdomain.duckdns.org` | Wiki platform | ✓ | MariaDB | +| **Form.io** | `https://forms.yourdomain.duckdns.org` | Form builder | ✓ | MongoDB | + +===== Home Automation ===== + +**Smart home integration and monitoring.** + +| Service | URL | Purpose | SSO | +|---------|-----|---------|-----| +| **Home Assistant** | `https://ha.yourdomain.duckdns.org` | Home automation | ✗ | +| **ESPHome** | `https://esphome.yourdomain.duckdns.org` | ESP firmware | ✓ | +| **TasmoAdmin** | `https://tasmoadmin.yourdomain.duckdns.org` | Tasmota manager | ✓ | +| **Node-RED** | `https://nodered.yourdomain.duckdns.org` | Automation flows | ✓ | +| **Mosquitto** | - | MQTT broker | - | +| **Zigbee2MQTT** | `https://zigbee2mqtt.yourdomain.duckdns.org` | Zigbee bridge | ✓ | +| **MotionEye** | `https://motioneye.yourdomain.duckdns.org` | Video surveillance | ✓ | + +===== Monitoring Services ===== + +**Observability, metrics, and alerting.** + +| Service | URL | Purpose | SSO | +|---------|-----|---------|-----| +| **Prometheus** | `https://prometheus.yourdomain.duckdns.org` | Metrics collection | ✓ | +| **Grafana** | `https://grafana.yourdomain.duckdns.org` | Dashboard platform | ✓ | +| **Loki** | - | Log aggregation | - | +| **Promtail** | - | Log shipping | - | +| **Node Exporter** | - | System metrics | - | +| **cAdvisor** | - | Container metrics | - | +| **Uptime Kuma** | `https://status.yourdomain.duckdns.org` | Status monitoring | ✓ | + +===== Utility Services ===== + +**Backup, password management, and miscellaneous.** + +| Service | URL | Purpose | SSO | +|---------|-----|---------|-----| +| **Vaultwarden** | `https://bitwarden.yourdomain.duckdns.org` | Password manager | ✗ | +| **Backrest** | `https://backrest.yourdomain.duckdns.org` | Backup manager | ✓ | +| **Duplicati** | `https://duplicati.yourdomain.duckdns.org` | Encrypted backups | ✓ | +| **FreshRSS** | `https://rss.yourdomain.duckdns.org` | RSS reader | ✓ | +| **Wallabag** | `https://wallabag.yourdomain.duckdns.org` | Read-it-later | ✓ | +| **Authelia Redis** | - | Session storage | - | + +===== Development Services ===== + +**Development tools and environments.** + +| Service | URL | Purpose | SSO | +|---------|-----|---------|-----| +| **GitLab CE** | `https://gitlab.yourdomain.duckdns.org` | DevOps platform | ✓ | +| **PostgreSQL** | - | SQL database | - | +| **Redis** | - | In-memory store | - | +| **pgAdmin** | `https://pgadmin.yourdomain.duckdns.org` | Database admin | ✓ | +| **Jupyter Lab** | `https://jupyter.yourdomain.duckdns.org` | Notebooks | ✓ | +| **Code Server** | `https://code.yourdomain.duckdns.org` | VS Code | ✓ | + +===== Alternative Services ===== + +**Alternative implementations and additional options.** + +| Service | URL | Purpose | SSO | Database | +|---------|-----|---------|-----|----------| +| **Plex** | `https://plex.yourdomain.duckdns.org` | Media server (Alt) | ✗ | - | +| **Portainer** | `https://portainer.yourdomain.duckdns.org` | Container manager | ✓ | - | +| **Authentik** | `https://authentik.yourdomain.duckdns.org` | SSO platform | ✓ | PostgreSQL | +| **Authentik Worker** | - | Background tasks | - | - | +| **Authentik DB** | - | Authentik database | - | - | +| **Authentik Redis** | - | Caching | - | - | + +**Legend:** ✓ = Protected by Authelia SSO | ✗ = Bypasses SSO | - = No web interface + +===== Service Management ===== + +**Deploying Services:** + +**Via Dockge (Recommended):** + 1. Access `https://dockge.yourdomain.duckdns.org` + 2. Click **"Add Stack"** + 3. Choose **"From Docker Compose"** + 4. Select compose file from repository + 5. Click **"Deploy"** + +**Via Command Line:** +```bash +# Deploy media services +docker compose -f docker-compose/media.yml up -d + +# Deploy productivity stack +docker compose -f docker-compose/productivity.yml up -d +``` + +**Managing Services:** +```bash +# View service status +docker compose -f docker-compose/stack.yml ps + +# View logs +docker compose -f docker-compose/stack.yml logs -f service-name + +# Restart service +docker compose -f docker-compose/stack.yml restart service-name + +# Stop service +docker compose -f docker-compose/stack.yml stop service-name +``` + +===== SSO Configuration ===== + +**Enabling SSO Protection:** +```yaml +labels: + - "traefik.http.routers.service.middlewares=authelia@docker" +``` + +**Disabling SSO (for media apps):** +```yaml +# Comment out the middleware line +# - "traefik.http.routers.service.middlewares=authelia@docker" +``` + +**Bypass Rules in Authelia:** +```yaml +access_control: + rules: + - domain: jellyfin.yourdomain.duckdns.org + policy: bypass + - domain: plex.yourdomain.duckdns.org + policy: bypass +``` + +===== Resource Management ===== + +**Default Resource Limits:** +```yaml +deploy: + resources: + limits: + cpus: '2.0' + memory: 4G + reservations: + cpus: '0.5' + memory: 1G +``` + +**Service Categories:** + * **Core**: 0.1-0.5 CPU, 64MB-256MB RAM + * **Web Services**: 1-2 CPU, 1-4GB RAM + * **Media Services**: 2-4 CPU, 4-8GB RAM + * **Databases**: 1-2 CPU, 2-4GB RAM + +===== Storage Requirements ===== + +**Configuration Storage (/opt/stacks/):** + * Small configs and metadata + * Automatic backups + * Version controlled + +**Data Storage (/mnt/):** + * Large media libraries + * User uploaded content + * Database files + +**Backup Storage:** + * Configuration backups + * User data archives + * SSL certificates + +===== Troubleshooting ===== + +**Service Won't Start:** +```bash +# Check logs +docker compose -f docker-compose/stack.yml logs service-name + +# Validate configuration +docker compose -f docker-compose/stack.yml config + +# Check resource usage +docker stats +``` + +**Access Issues:** + * Verify Traefik labels + * Check Authelia policies + * Confirm DNS resolution + * Test SSL certificates + +**Performance Problems:** + * Monitor resource usage + * Check network connectivity + * Review service logs + * Adjust resource limits + +**Next:** Explore individual [[services:core:start|Core Services]] or learn about [[troubleshooting:start|Troubleshooting]]. \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/sidebar.txt b/config-templates/dokuwiki/data/pages/sidebar.txt new file mode 100644 index 0000000..c1bb6c7 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/sidebar.txt @@ -0,0 +1,84 @@ +====== Navigation ====== + +**AI-Homelab Wiki** + +==== Getting Started ==== + * [[getting_started:start|Overview]] + * [[getting_started:prerequisites|Prerequisites]] + * [[getting_started:setup|Automated Setup]] + * [[getting_started:deployment|Deployment]] + * [[getting_started:access|Access Services]] + * [[getting_started:security|Security Setup]] + +==== Architecture ==== + * [[architecture:overview|System Overview]] + * [[architecture:networking|Network Architecture]] + * [[architecture:security|Security Model]] + * [[architecture:storage|Storage Strategy]] + * [[architecture:backup|Backup Strategy]] + +==== Services ==== + * [[services:start|Service Overview]] + * **Core Infrastructure** + * [[services:core:traefik|Traefik]] + * [[services:core:authelia|Authelia]] + * [[services:core:duckdns|DuckDNS]] + * [[services:core:gluetun|Gluetun]] + * [[services:core:sablier|Sablier]] + * **Infrastructure** + * [[services:infrastructure:dockge|Dockge]] + * [[services:infrastructure:pihole|Pi-hole]] + * [[services:infrastructure:dozzle|Dozzle]] + * [[services:infrastructure:glances|Glances]] + * **Media Services** + * [[services:media:jellyfin|Jellyfin]] + * [[services:media:plex|Plex]] + * [[services:media:qbittorrent|qBittorrent]] + * [[services:media:sonarr|Sonarr]] + * [[services:media:radarr|Radarr]] + * **Productivity** + * [[services:productivity:nextcloud|Nextcloud]] + * [[services:productivity:gitea|Gitea]] + * [[services:productivity:bookstack|BookStack]] + * **Monitoring** + * [[services:monitoring:grafana|Grafana]] + * [[services:monitoring:prometheus|Prometheus]] + * [[services:monitoring:uptime_kuma|Uptime Kuma]] + * **Utilities** + * [[services:utilities:backrest|Backrest]] + * [[services:utilities:duplicati|Duplicati]] + * [[services:utilities:vaultwarden|Vaultwarden]] + +==== Backup & Recovery ==== + * [[backup_recovery:start|Overview]] + * [[backup_recovery:backrest|Backrest (Default)]] + * [[backup_recovery:duplicati|Duplicati (Alternative)]] + * [[backup_recovery:strategy|Backup Strategy]] + * [[backup_recovery:restoration|Restoration]] + +==== Troubleshooting ==== + * [[troubleshooting:start|Common Issues]] + * [[troubleshooting:deployment|Deployment Problems]] + * [[troubleshooting:services|Service Issues]] + * [[troubleshooting:networking|Network Problems]] + * [[troubleshooting:ssl|SSL Certificate Issues]] + +==== Development ==== + * [[development:start|Contributing]] + * [[development:copilot|AI Copilot Integration]] + * [[development:customization|Customization]] + * [[development:deployment|Advanced Deployment]] + +==== Reference ==== + * [[reference:start|Quick Reference]] + * [[reference:commands|Command Reference]] + * [[reference:environment|Environment Variables]] + * [[reference:ports|Port Reference]] + * [[reference:scripts|Deployment Scripts]] + +==== External Links ==== + * [[https://github.com/kelinfoxy/AI-Homelab|GitHub Repository]] + * [[https://github.com/kelinfoxy/AI-Homelab/issues|Issue Tracker]] + * [[https://github.com/kelinfoxy/AI-Homelab/discussions|Discussions]] + * [[https://doc.traefik.io/traefik/|Traefik Documentation]] + * [[https://www.authelia.com/|Authelia Documentation]] \ No newline at end of file diff --git a/config-templates/dokuwiki/data/pages/start.txt b/config-templates/dokuwiki/data/pages/start.txt new file mode 100644 index 0000000..c733c19 --- /dev/null +++ b/config-templates/dokuwiki/data/pages/start.txt @@ -0,0 +1,109 @@ +====== AI-Homelab Documentation Wiki ====== + +{{:ai-homelab-logo.png?200|AI-Homelab Logo}} + +===== Welcome to AI-Homelab ===== + +**AI-Homelab** is a production-ready homelab infrastructure that deploys 70+ services through a file-based, AI-manageable architecture using Dockge for visual management. + +**Key Features:** + * **Automated SSL** - Wildcard certificates via Let's Encrypt + * **Single Sign-On** - Authelia authentication across all services + * **VPN Routing** - Secure downloads through Gluetun + * **Lazy Loading** - Sablier enables on-demand container startup + * **Resource Limits** - Prevent resource exhaustion + * **AI Management** - GitHub Copilot integration for service management + +**Quick Access:** + * [[getting_started:start|🚀 Getting Started]] - Setup and deployment guide + * [[architecture:overview|🏗️ Architecture]] - System design and components + * [[services:start|📦 Services]] - All available services and stacks + * [[backup_recovery:start|💾 Backup & Recovery]] - Data protection strategies + * [[troubleshooting:start|🔧 Troubleshooting]] - Common issues and solutions + * [[development:start|👨‍💻 Development]] - Contributing and customization + +===== Quick Start Checklist ===== + +Complete these steps to get your homelab running: + + * [ ] [[getting_started:prerequisites|Review prerequisites and requirements]] + * [ ] [[getting_started:setup|Run automated setup script]] + * [ ] [[getting_started:deployment|Deploy core infrastructure]] + * [ ] [[getting_started:access|Access your services]] + * [ ] [[getting_started:security|Configure security (2FA, access rules)]] + * [ ] [[services:deployment|Deploy additional services as needed]] + +===== Architecture Overview ===== + +{{:architecture-diagram.png?400|Architecture Diagram}} + +**Core Components:** + * **[[services:core:traefik|Traefik]]** - Reverse proxy with automatic SSL + * **[[services:core:authelia|Authelia]]** - Single sign-on authentication + * **[[services:core:duckdns|DuckDNS]]** - Dynamic DNS updates + * **[[services:core:gluetun|Gluetun]]** - VPN client for secure downloads + * **[[services:core:sablier|Sablier]]** - Lazy loading service + +**Service Categories:** + * **[[services:infrastructure:start|Infrastructure]]** - Management and monitoring tools + * **[[services:media:start|Media]]** - Streaming, automation, and content management + * **[[services:productivity:start|Productivity]]** - Collaboration and workflow tools + * **[[services:monitoring:start|Monitoring]]** - Observability and alerting + * **[[services:utilities:start|Utilities]]** - Backup, security, and system tools + +===== Service Access ===== + +After deployment, access your services at: + +^ Service ^ URL ^ Authentication ^ +| **Dockge** | https://dockge.{{DOMAIN}} | Authelia SSO | +| **Homepage** | https://home.{{DOMAIN}} | Authelia SSO | +| **Traefik Dashboard** | https://traefik.{{DOMAIN}} | Authelia SSO | +| **Authelia Login** | https://auth.{{DOMAIN}} | Direct access | + +===== Getting Help ===== + +**Documentation Navigation:** + * Use the sidebar for quick navigation + * Search functionality is available in the top-right + * All pages include cross-references to related topics + +**Community Resources:** + * [[https://github.com/kelinfoxy/AI-Homelab|GitHub Repository]] + * [[https://github.com/kelinfoxy/AI-Homelab/issues|Issue Tracker]] + * [[https://github.com/kelinfoxy/AI-Homelab/discussions|Discussions]] + +**AI Assistance:** + * This wiki is designed to work with AI agents + * Use GitHub Copilot in VS Code for intelligent management + * See [[development:copilot|Copilot Instructions]] for details + +===== Recent Updates ===== + +**January 20, 2026:** + * Updated service count to 70+ services + * Enhanced Sablier lazy loading documentation + * Improved backup strategy with Backrest as default + * Standardized service documentation format + * Added comprehensive troubleshooting guides + +**Key Improvements:** + * Better navigation and cross-linking + * Comprehensive service documentation + * Enhanced security configurations + * Improved deployment automation + +===== Navigation ===== + +{{:navigation-tree.png?300|Documentation Structure}} + +**Main Sections:** + * [[getting_started:start|Getting Started]] - Setup and deployment + * [[architecture:start|Architecture]] - System design + * [[services:start|Services]] - Available services + * [[backup_recovery:start|Backup & Recovery]] - Data protection + * [[troubleshooting:start|Troubleshooting]] - Problem solving + * [[development:start|Development]] - Contributing and customization + * [[reference:start|Reference]] - Quick reference guides + +This wiki serves as the comprehensive documentation hub for AI-Homelab. All content is maintained and regularly updated to reflect the latest features and best practices. \ No newline at end of file diff --git a/config-templates/dokuwiki/docker-compose.yml b/config-templates/dokuwiki/docker-compose.yml new file mode 100644 index 0000000..25340f7 --- /dev/null +++ b/config-templates/dokuwiki/docker-compose.yml @@ -0,0 +1,33 @@ +# Dokuwiki - Self-hosted Wiki Platform +# Place in /opt/stacks/productivity/dokuwiki/docker-compose.yml + +services: + dokuwiki: + image: lscr.io/linuxserver/dokuwiki:latest + container_name: dokuwiki + restart: unless-stopped + networks: + - traefik-network + volumes: + - ./config:/config + environment: + - PUID=${PUID:-1000} + - PGID=${PGID:-1000} + - TZ=${TZ} + labels: + - "homelab.category=productivity" + - "homelab.description=Self-hosted wiki platform" + - "traefik.enable=true" + - "traefik.http.routers.dokuwiki.rule=Host(`wiki.${DOMAIN}`)" + - "traefik.http.routers.dokuwiki.entrypoints=websecure" + - "traefik.http.routers.dokuwiki.tls.certresolver=letsencrypt" + - "traefik.http.routers.dokuwiki.middlewares=authelia@docker" + - "traefik.http.services.dokuwiki.loadbalancer.server.port=80" + - "x-dockge.url=https://wiki.${DOMAIN}" + +volumes: + dokuwiki-config: + +networks: + traefik-network: + external: true \ No newline at end of file