Complete documentation refactoring with 57 service docs

- Refactored README.md, getting-started.md, quick-reference.md - Enhanced setup-homelab.sh with 9-step automated process - Created services-overview.md with all stacks - Added comprehensive documentation for 57 services in docs/service-docs/ - All services include: overview, configuration, resources, educational content - Coverage: Core, Infrastructure, Dashboards, Media, Media-Extended, Home Assistant, Productivity, Utilities, Monitoring, Development stacks - Educational focus with links to tutorials, videos, and guides
2026-01-12 18:03:12 -05:00
parent 906e6008ea
commit cba45556c7
69 changed files with 24404 additions and 1522 deletions
--- a/docs/service-docs/docker-proxy.md
+++ b/docs/service-docs/docker-proxy.md
@@ -0,0 +1,680 @@
+# Docker Socket Proxy - Secure Docker Socket Access
+
+## Table of Contents
+- [Overview](#overview)
+- [What is Docker Socket Proxy?](#what-is-docker-socket-proxy)
+- [Why Use Docker Socket Proxy?](#why-use-docker-socket-proxy)
+- [How It Works](#how-it-works)
+- [Configuration in AI-Homelab](#configuration-in-ai-homelab)
+- [Official Resources](#official-resources)
+- [Educational Resources](#educational-resources)
+- [Docker Configuration](#docker-configuration)
+- [Access Control](#access-control)
+- [Advanced Topics](#advanced-topics)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+**Category:** Infrastructure Security  
+**Docker Image:** [tecnativa/docker-socket-proxy](https://hub.docker.com/r/tecnativa/docker-socket-proxy)  
+**Default Stack:** `infrastructure.yml`  
+**Web UI:** None (proxy service)  
+**Port:** 2375 (internal only)  
+**Purpose:** Secure access layer for Docker socket
+
+## What is Docker Socket Proxy?
+
+Docker Socket Proxy is a security-focused proxy that sits between Docker management tools and the Docker socket. It provides fine-grained access control to Docker API endpoints, allowing you to grant specific permissions rather than full Docker socket access.
+
+### Key Features
+- **Granular Permissions:** Control which Docker API endpoints are accessible
+- **Security Layer:** Prevents full root access to host
+- **Read/Write Control:** Separate read-only and write permissions
+- **API Filtering:** Whitelist specific Docker API calls
+- **No Authentication:** Relies on network isolation
+- **Lightweight:** Minimal resource usage
+- **HAProxy Based:** Stable, proven technology
+- **Zero Config:** Works out of the box with sensible defaults
+
+## Why Use Docker Socket Proxy?
+
+### The Problem
+
+Direct Docker socket access (`/var/run/docker.sock`) grants **root-equivalent access** to the host:
+
+```yaml
+# DANGEROUS: Full access to Docker = root on host
+traefik:
+  volumes:
+    - /var/run/docker.sock:/var/run/docker.sock
+```
+
+**Risks:**
+- Container can access all other containers
+- Can mount host filesystem
+- Can escape container isolation
+- Can compromise entire system
+
+### The Solution
+
+Docker Socket Proxy provides controlled access:
+
+```yaml
+# SAFER: Limited access via proxy
+traefik:
+  environment:
+    - DOCKER_HOST=tcp://docker-proxy:2375
+# No direct socket mount!
+
+docker-proxy:
+  volumes:
+    - /var/run/docker.sock:/var/run/docker.sock:ro
+  environment:
+    - CONTAINERS=1  # Allow container list
+    - SERVICES=1    # Allow service list
+    - TASKS=0       # Deny task access
+```
+
+**Benefits:**
+1. **Principle of Least Privilege:** Only grant necessary permissions
+2. **Reduced Attack Surface:** Limit what compromised container can do
+3. **Audit Trail:** Centralized access point
+4. **Network Isolation:** Proxy can be on separate network
+5. **Read-Only Socket:** Proxy uses read-only mount
+
+## How It Works
+
+```
+Management Tool (Traefik/Portainer/Dockge)
+     ↓
+TCP Connection to docker-proxy:2375
+     ↓
+Docker Socket Proxy (HAProxy)
+     ├─ Check permissions
+     ├─ Filter allowed endpoints
+     └─ Forward or block request
+     ↓
+Docker Socket (/var/run/docker.sock)
+     ↓
+Docker Engine
+```
+
+### Request Flow
+
+1. **Tool makes API request:** "List containers"
+2. **Connects to proxy:** tcp://docker-proxy:2375
+3. **Proxy checks permissions:** Is CONTAINERS=1?
+4. **If allowed:** Forward to Docker socket
+5. **If denied:** Return 403 Forbidden
+6. **Response returned:** To requesting tool
+
+### Permission Model
+
+**Environment variables control access:**
+- `CONTAINERS=1` → Allow container operations
+- `IMAGES=1` → Allow image operations
+- `NETWORKS=1` → Allow network operations
+- `VOLUMES=1` → Allow volume operations
+- `SERVICES=1` → Allow swarm service operations
+- `TASKS=1` → Allow swarm task operations
+- `SECRETS=1` → Allow secret operations
+- `POST=0` → Deny all write operations (read-only)
+
+## Configuration in AI-Homelab
+
+### Directory Structure
+
+```
+# No persistent storage needed
+# All configuration via environment variables
+```
+
+### Environment Variables
+
+```bash
+# Core Docker API endpoints
+CONTAINERS=1    # Container list, inspect, logs, stats
+SERVICES=1      # Service management (for Swarm)
+TASKS=1         # Task management (for Swarm)
+NETWORKS=1      # Network operations
+VOLUMES=1       # Volume operations
+IMAGES=1        # Image list, pull, push
+INFO=1          # Docker info, version
+EVENTS=1        # Docker events stream
+PING=1          # Health check
+
+# Write operations (set to 0 for read-only)
+POST=1          # Create operations
+BUILD=0         # Image build (usually not needed)
+COMMIT=0        # Container commit
+CONFIGS=0       # Config management
+DISTRIBUTION=0  # Registry operations
+EXEC=0          # Execute in container (dangerous)
+SECRETS=0       # Secret management (Swarm)
+SESSION=0       # Not commonly used
+SWARM=0         # Swarm management
+
+# Security
+LOG_LEVEL=info  # Logging verbosity
+```
+
+## Official Resources
+
+- **GitHub:** https://github.com/Tecnativa/docker-socket-proxy
+- **Docker Hub:** https://hub.docker.com/r/tecnativa/docker-socket-proxy
+- **Documentation:** https://github.com/Tecnativa/docker-socket-proxy/blob/master/README.md
+
+## Educational Resources
+
+### Videos
+- [Docker Socket Security (TechnoTim)](https://www.youtube.com/watch?v=0aOqx8mQZFk)
+- [Why You Should Use Docker Socket Proxy](https://www.youtube.com/results?search_query=docker+socket+proxy+security)
+- [Container Security Best Practices](https://www.youtube.com/watch?v=9weaE6QEm8A)
+
+### Articles & Guides
+- [Docker Socket Proxy Documentation](https://github.com/Tecnativa/docker-socket-proxy)
+- [Docker Socket Security Risks](https://docs.docker.com/engine/security/)
+- [Principle of Least Privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)
+
+### Concepts to Learn
+- **Unix Socket:** Inter-process communication file
+- **Docker API:** RESTful API for Docker operations
+- **TCP Socket:** Network socket for remote access
+- **HAProxy:** Load balancer and proxy
+- **Least Privilege:** Minimal permissions principle
+- **Attack Surface:** Potential vulnerability points
+- **Container Escape:** Breaking out of container isolation
+
+## Docker Configuration
+
+### Complete Service Definition
+
+```yaml
+docker-proxy:
+  image: tecnativa/docker-socket-proxy:latest
+  container_name: docker-proxy
+  restart: unless-stopped
+  privileged: true  # Required for socket access
+  networks:
+    - docker-proxy-network  # Isolated network
+  ports:
+    - "2375:2375"  # Only expose internally
+  volumes:
+    - /var/run/docker.sock:/var/run/docker.sock:ro  # Read-only!
+  environment:
+    # Core permissions (what Traefik/Portainer need)
+    - CONTAINERS=1
+    - SERVICES=1
+    - NETWORKS=1
+    - IMAGES=1
+    - INFO=1
+    - EVENTS=1
+    - PING=1
+    
+    # Write operations (enable as needed)
+    - POST=1
+    
+    # Deny dangerous operations
+    - BUILD=0
+    - COMMIT=0
+    - EXEC=0
+    - SECRETS=0
+    
+    # Logging
+    - LOG_LEVEL=info
+
+networks:
+  docker-proxy-network:
+    internal: true  # No external access
+```
+
+### Connecting Services to Proxy
+
+**Traefik Configuration:**
+```yaml
+traefik:
+  networks:
+    - traefik-network
+    - docker-proxy-network
+  environment:
+    - DOCKER_HOST=tcp://docker-proxy:2375
+  # NO volumes for Docker socket!
+  # volumes:
+  #   - /var/run/docker.sock:/var/run/docker.sock  # REMOVE THIS
+```
+
+**Portainer Configuration:**
+```yaml
+portainer:
+  networks:
+    - traefik-network
+    - docker-proxy-network
+  environment:
+    - AGENT_HOST=docker-proxy
+  # NO volumes for Docker socket!
+```
+
+**Dockge Configuration:**
+```yaml
+dockge:
+  networks:
+    - traefik-network
+    - docker-proxy-network
+  environment:
+    - DOCKER_HOST=tcp://docker-proxy:2375
+  # NO volumes for Docker socket!
+```
+
+## Access Control
+
+### Traefik Minimal Permissions
+
+Traefik only needs to read container labels:
+
+```yaml
+docker-proxy:
+  environment:
+    - CONTAINERS=1  # Read container info
+    - SERVICES=1    # Read services
+    - NETWORKS=1    # Read networks
+    - INFO=1        # Docker info
+    - EVENTS=1      # Watch for changes
+    - POST=0        # No write operations
+```
+
+### Portainer Full Permissions
+
+Portainer needs more access for management:
+
+```yaml
+docker-proxy:
+  environment:
+    - CONTAINERS=1
+    - SERVICES=1
+    - TASKS=1
+    - NETWORKS=1
+    - VOLUMES=1
+    - IMAGES=1
+    - INFO=1
+    - EVENTS=1
+    - POST=1        # Create/update
+    - PING=1
+```
+
+### Watchtower Minimal Permissions
+
+Watchtower needs to pull images and recreate containers:
+
+```yaml
+docker-proxy:
+  environment:
+    - CONTAINERS=1
+    - IMAGES=1
+    - INFO=1
+    - POST=1        # Create operations
+```
+
+### Read-Only Mode
+
+For monitoring tools (Glances, Dozzle):
+
+```yaml
+docker-proxy:
+  environment:
+    - CONTAINERS=1
+    - SERVICES=1
+    - TASKS=1
+    - NETWORKS=1
+    - VOLUMES=1
+    - IMAGES=1
+    - INFO=1
+    - EVENTS=1
+    - POST=0        # No writes
+    - BUILD=0
+    - COMMIT=0
+    - EXEC=0
+```
+
+## Advanced Topics
+
+### Multiple Proxy Instances
+
+Run separate proxies for different permission levels:
+
+**docker-proxy-read (for monitoring tools):**
+```yaml
+docker-proxy-read:
+  image: tecnativa/docker-socket-proxy
+  environment:
+    - CONTAINERS=1
+    - IMAGES=1
+    - INFO=1
+    - POST=0  # Read-only
+  networks:
+    - monitoring-network
+```
+
+**docker-proxy-write (for management tools):**
+```yaml
+docker-proxy-write:
+  image: tecnativa/docker-socket-proxy
+  environment:
+    - CONTAINERS=1
+    - IMAGES=1
+    - NETWORKS=1
+    - VOLUMES=1
+    - POST=1  # Read-write
+  networks:
+    - management-network
+```
+
+### Custom HAProxy Configuration
+
+For advanced filtering, mount custom config:
+
+```yaml
+docker-proxy:
+  volumes:
+    - /var/run/docker.sock:/var/run/docker.sock:ro
+    - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
+```
+
+**Custom haproxy.cfg:**
+```haproxy
+global
+    log stdout format raw local0
+
+defaults
+    log global
+    mode http
+    timeout connect 5s
+    timeout client 30s
+    timeout server 30s
+
+frontend docker
+    bind :2375
+    default_backend docker_backend
+
+backend docker_backend
+    server docker unix@/var/run/docker.sock
+    
+    # Custom ACLs
+    acl containers_req path_beg /containers
+    acl images_req path_beg /images
+    
+    # Only allow specific endpoints
+    http-request deny unless containers_req or images_req
+```
+
+### Logging and Monitoring
+
+```yaml
+docker-proxy:
+  environment:
+    - LOG_LEVEL=debug  # More verbose logging
+  logging:
+    driver: json-file
+    options:
+      max-size: "10m"
+      max-file: "3"
+```
+
+**Monitor access:**
+```bash
+# View proxy logs
+docker logs -f docker-proxy
+
+# See what endpoints are being accessed
+docker logs docker-proxy | grep -E "GET|POST|PUT|DELETE"
+```
+
+### Network Isolation
+
+```yaml
+networks:
+  docker-proxy-network:
+    driver: bridge
+    internal: true  # No internet access
+    ipam:
+      config:
+        - subnet: 172.25.0.0/16
+```
+
+**Only allow specific services:**
+```yaml
+services:
+  traefik:
+    networks:
+      docker-proxy-network:
+        ipv4_address: 172.25.0.2
+  
+  portainer:
+    networks:
+      docker-proxy-network:
+        ipv4_address: 172.25.0.3
+```
+
+## Troubleshooting
+
+### Services Can't Connect to Docker
+
+```bash
+# Check if proxy is running
+docker ps | grep docker-proxy
+
+# Test proxy connectivity
+docker exec traefik wget -qO- http://docker-proxy:2375/version
+
+# Check networks
+docker network inspect docker-proxy-network
+
+# Verify service is on proxy network
+docker inspect traefik | grep -A10 Networks
+```
+
+### Permission Denied Errors
+
+```bash
+# Check proxy logs
+docker logs docker-proxy
+
+# Example error: "POST /containers/create 403"
+# Solution: Add POST=1 to docker-proxy environment
+
+# Check which endpoint is being blocked
+docker logs docker-proxy | grep 403
+
+# Enable required permission
+# If /images/create is blocked, add IMAGES=1
+```
+
+### Traefik Not Discovering Services
+
+```bash
+# Ensure these are enabled:
+docker-proxy:
+  environment:
+    - CONTAINERS=1
+    - SERVICES=1
+    - EVENTS=1  # Critical for auto-discovery
+
+# Check if Traefik is using proxy
+docker exec traefik env | grep DOCKER_HOST
+
+# Test manually
+docker exec traefik wget -qO- http://docker-proxy:2375/containers/json
+```
+
+### Portainer Shows "Cannot connect to Docker"
+
+```bash
+# Portainer needs more permissions
+docker-proxy:
+  environment:
+    - CONTAINERS=1
+    - SERVICES=1
+    - TASKS=1
+    - NETWORKS=1
+    - VOLUMES=1
+    - IMAGES=1
+    - POST=1
+
+# In Portainer settings:
+# Environment URL: tcp://docker-proxy:2375
+# Not: unix:///var/run/docker.sock
+```
+
+### Watchtower Not Updating Containers
+
+```bash
+# Watchtower needs write access
+docker-proxy:
+  environment:
+    - CONTAINERS=1
+    - IMAGES=1
+    - POST=1  # Required for creating containers
+
+# Check Watchtower logs
+docker logs watchtower
+```
+
+### High Memory/CPU Usage
+
+```bash
+# Check proxy stats
+docker stats docker-proxy
+
+# Should be minimal (~10MB RAM, <1% CPU)
+# If high, check for connection leaks
+
+# Restart proxy
+docker restart docker-proxy
+
+# Check for excessive requests
+docker logs docker-proxy | wc -l
+```
+
+## Security Best Practices
+
+1. **Read-Only Socket:** Always mount socket as `:ro`
+2. **Minimal Permissions:** Only enable what's needed
+3. **Network Isolation:** Use internal network
+4. **No Public Exposure:** Never expose port 2375 to internet
+5. **Separate Proxies:** Different proxies for different trust levels
+6. **Monitor Access:** Review logs regularly
+7. **Disable Exec:** Never enable EXEC unless absolutely necessary
+8. **Regular Updates:** Keep proxy image updated
+9. **Principle of Least Privilege:** Start with nothing, add as needed
+10. **Testing:** Test permissions in development first
+
+## Migration Guide
+
+### Converting from Direct Socket Access
+
+**Before (insecure):**
+```yaml
+traefik:
+  volumes:
+    - /var/run/docker.sock:/var/run/docker.sock
+```
+
+**After (secure):**
+
+1. **Add docker-proxy:**
+```yaml
+docker-proxy:
+  image: tecnativa/docker-socket-proxy
+  volumes:
+    - /var/run/docker.sock:/var/run/docker.sock:ro
+  environment:
+    - CONTAINERS=1
+    - SERVICES=1
+    - NETWORKS=1
+    - EVENTS=1
+  networks:
+    - docker-proxy-network
+```
+
+2. **Update service:**
+```yaml
+traefik:
+  environment:
+    - DOCKER_HOST=tcp://docker-proxy:2375
+  networks:
+    - traefik-network
+    - docker-proxy-network
+  # Remove socket volume!
+```
+
+3. **Create network:**
+```yaml
+networks:
+  docker-proxy-network:
+    internal: true
+```
+
+4. **Test:**
+```bash
+docker compose up -d
+docker logs traefik  # Check for errors
+```
+
+## Performance Impact
+
+**Overhead:**
+- Latency: ~1-2ms per request
+- Memory: ~10-20MB
+- CPU: <1%
+
+**Minimal impact because:**
+- Docker API calls are infrequent
+- Proxy is extremely lightweight
+- HAProxy is optimized for performance
+
+**Benchmark:**
+```bash
+# Direct socket
+time docker ps
+# ~0.05s
+
+# Via proxy
+time docker -H tcp://docker-proxy:2375 ps
+# ~0.06s
+
+# Negligible difference for management operations
+```
+
+## Summary
+
+Docker Socket Proxy is a critical security component that:
+- Provides granular access control to Docker API
+- Prevents root-equivalent access from containers
+- Uses principle of least privilege
+- Adds minimal overhead
+- Simple to configure and maintain
+
+**Essential for:**
+- Production environments
+- Multi-user setups
+- Security-conscious homelabs
+- Compliance requirements
+- Defense in depth strategy
+
+**Implementation Priority:**
+1. Deploy docker-proxy with minimal permissions
+2. Update Traefik to use proxy (most critical)
+3. Update Portainer to use proxy
+4. Update other management tools
+5. Remove all direct socket mounts
+6. Test thoroughly
+7. Monitor logs
+
+**Remember:**
+- Direct socket access = root on host
+- Always use read-only socket mount in proxy
+- Start with restrictive permissions
+- Add permissions only as needed
+- Use separate proxies for different trust levels
+- Never expose proxy to internet
+- Monitor access logs
+- Essential security layer for homelab