Wiki v1.0
Added a wiki
This commit is contained in:
kelinfoxy
293
config-templates/dokuwiki/data/pages/architecture/backup.txt
Normal file
293
config-templates/dokuwiki/data/pages/architecture/backup.txt
Normal file
@@ -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]].
|
||||
329
config-templates/dokuwiki/data/pages/architecture/networking.txt
Normal file
329
config-templates/dokuwiki/data/pages/architecture/networking.txt
Normal file
@@ -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]].
|
||||
298
config-templates/dokuwiki/data/pages/architecture/overview.txt
Normal file
298
config-templates/dokuwiki/data/pages/architecture/overview.txt
Normal file
@@ -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]].
|
||||
299
config-templates/dokuwiki/data/pages/architecture/security.txt
Normal file
299
config-templates/dokuwiki/data/pages/architecture/security.txt
Normal file
@@ -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]].
|
||||
291
config-templates/dokuwiki/data/pages/architecture/storage.txt
Normal file
291
config-templates/dokuwiki/data/pages/architecture/storage.txt
Normal file
@@ -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]].
|
||||
251
config-templates/dokuwiki/data/pages/getting_started/access.txt
Normal file
251
config-templates/dokuwiki/data/pages/getting_started/access.txt
Normal file
@@ -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]].
|
||||
@@ -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]].
|
||||
@@ -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]].
|
||||
@@ -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]].
|
||||
234
config-templates/dokuwiki/data/pages/getting_started/setup.txt
Normal file
234
config-templates/dokuwiki/data/pages/getting_started/setup.txt
Normal file
@@ -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]].
|
||||
126
config-templates/dokuwiki/data/pages/getting_started/start.txt
Normal file
126
config-templates/dokuwiki/data/pages/getting_started/start.txt
Normal file
@@ -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]].
|
||||
420
config-templates/dokuwiki/data/pages/services/core/authelia.txt
Normal file
420
config-templates/dokuwiki/data/pages/services/core/authelia.txt
Normal file
@@ -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]].
|
||||
289
config-templates/dokuwiki/data/pages/services/core/duckdns.txt
Normal file
289
config-templates/dokuwiki/data/pages/services/core/duckdns.txt
Normal file
@@ -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]].
|
||||
404
config-templates/dokuwiki/data/pages/services/core/gluetun.txt
Normal file
404
config-templates/dokuwiki/data/pages/services/core/gluetun.txt
Normal file
@@ -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]].
|
||||
401
config-templates/dokuwiki/data/pages/services/core/sablier.txt
Normal file
401
config-templates/dokuwiki/data/pages/services/core/sablier.txt
Normal file
@@ -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]].
|
||||
366
config-templates/dokuwiki/data/pages/services/core/traefik.txt
Normal file
366
config-templates/dokuwiki/data/pages/services/core/traefik.txt
Normal file
@@ -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]].
|
||||
@@ -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]].
|
||||
@@ -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]].
|
||||
@@ -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]].
|
||||
@@ -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]].
|
||||
@@ -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]].
|
||||
@@ -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]].
|
||||
@@ -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]].
|
||||
@@ -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]].
|
||||
424
config-templates/dokuwiki/data/pages/services/media/jellyfin.txt
Normal file
424
config-templates/dokuwiki/data/pages/services/media/jellyfin.txt
Normal file
@@ -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]].
|
||||
@@ -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]].
|
||||
194
config-templates/dokuwiki/data/pages/services/media/start.txt
Normal file
194
config-templates/dokuwiki/data/pages/services/media/start.txt
Normal file
@@ -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]].
|
||||
282
config-templates/dokuwiki/data/pages/services/start.txt
Normal file
282
config-templates/dokuwiki/data/pages/services/start.txt
Normal file
@@ -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]].
|
||||
84
config-templates/dokuwiki/data/pages/sidebar.txt
Normal file
84
config-templates/dokuwiki/data/pages/sidebar.txt
Normal file
@@ -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]]
|
||||
109
config-templates/dokuwiki/data/pages/start.txt
Normal file
109
config-templates/dokuwiki/data/pages/start.txt
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user