homelab-blueprint/docs/IMPROVEMENTS.md

Docker Compose Improvements

Overview

This document outlines the comprehensive improvements made to all Docker Compose template files in this repository. These changes follow best practices for production-ready containerized applications, with special consideration for Synology NAS deployments.

Summary of Changes

Global Improvements Applied to All Templates

1. Version Specification

   • Added version: '3.8' to all compose files for compatibility and feature support
   • Enables advanced features like healthchecks, resource limits, and dependency conditions

2. Environment Variable Format

   • Converted from array format (- KEY=value) to map format (KEY: value)
   • Improves readability and maintainability
   • Consistent with Docker Compose v3+ best practices

3. Resource Limits

   • Added CPU and memory limits/reservations to all services
   • Prevents resource exhaustion and ensures system stability
   • Tailored limits based on typical service requirements

4. Health Checks

   • Implemented comprehensive healthcheck configurations
   • Includes proper start_period to allow services time to initialize
   • Services can now properly wait for dependencies to be healthy

5. Dependency Management

   • Upgraded depends_on to use condition: service_healthy
   • Ensures services start only when dependencies are ready
   • Prevents cascading failures and startup issues

6. Security Hardening

   • Added security_opt: no-new-privileges:true to all services
   • Prevents privilege escalation attacks
   • Read-only mounts where appropriate (e.g., docker.sock)

7. Logging Configuration

   • Standardized logging across all services using json-file driver
   • Uses centralized DOCKERLOGGING_MAXFILE and DOCKERLOGGING_MAXSIZE variables
   • Prevents disk space exhaustion from unlimited logs

8. Labels for Organization

   • Added descriptive labels to all services and networks
   • Format: com.synology.stack and com.synology.service
   • Improves service discovery and management in Synology DSM

9. Restart Policies

   • Standardized to unless-stopped across all services
   • More predictable behavior than always
   • Services won't auto-restart if manually stopped

10. Network Configuration

    • Moved network definitions to bottom of files (convention)
    • Added explicit network names and labels
    • Better organization and documentation

11. Image Version Tags

    • Added :latest tag where missing for clarity
    • Explicit version pinning where stability is critical (e.g., Vault)

---

File-Specific Improvements

1. postgres_template.yaml

Services Modified: postgres, pgadmin

Key Changes:

• PostgreSQL

  • Added healthcheck using pg_isready
  • Resource limits: 2 CPU cores, 2GB RAM (max)
  • Added start_period: 30s for initialization time

• pgAdmin

  • Enhanced healthcheck using wget to ping endpoint
  • Added configuration for server mode and master password
  • Depends on postgres with service_healthy condition
  • Resource limits: 1 CPU core, 1GB RAM (max)

• Network

  • Named network: postgres_network
  • Added descriptive label

Example Healthcheck:

healthcheck:
  test: ["CMD-SHELL", "pg_isready -U {{POSTGRES_USER}} -d {{POSTGRES_DB}}"]
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 30s

---

2. arr-stack_template.yaml

Services Modified: gluetun, qbittorrent, flaresolverr, sabnzbd, prowlarr, radarr, sonarr, bazarr, emby, jellyseerr, recyclarr, watchtower

Key Changes:

VPN Services

• Gluetun

  • Healthcheck: Verifies internet connectivity through VPN
  • Resource limits: 1 CPU, 512MB RAM
  • Added TZ environment variable
  • Proper port documentation with comments

• qBittorrent

  • Depends on gluetun with health condition
  • Uses gluetun's network (network_mode: service:gluetun)
  • Resource limits: 2 CPUs, 1GB RAM for download processing

Indexer & Download Clients

• FlareSolverr

  • Added healthcheck using API endpoint
  • Resource limits: 1 CPU, 1GB RAM
  • Comprehensive environment configuration

• SABnzbd

  • Healthcheck monitors API availability
  • Resource limits: 2 CPUs, 2GB RAM for extraction

• Prowlarr

  • Depends on flaresolverr health
  • Added proper API healthcheck
  • Longer start_period (60s) for initialization

Media Management (Arr Stack)

• Radarr & Sonarr

  • Depend on both prowlarr and gluetun health
  • Consistent healthcheck implementation
  • Resource limits: 1 CPU, 1GB RAM each
  • Start period: 60s for database initialization

• Bazarr

  • Depends on both radarr and sonarr health
  • API-based healthcheck
  • Lighter resource limits: 0.5 CPU, 512MB RAM

Media Server

• Emby

  • Higher resource allocation: 4 CPUs, 4GB RAM
  • Longer start_period (90s) for library scanning
  • Hardware transcoding device properly mounted
  • Healthcheck monitors API health

• Jellyseerr

  • Depends on emby health
  • API status endpoint healthcheck
  • Resource limits: 0.5 CPU, 512MB RAM

Maintenance Tools

• Recyclarr

  • Depends on both radarr and sonarr health
  • Lightweight: 0.5 CPU, 256MB RAM
  • Proper user mapping with quotes

• Watchtower

  • Read-only docker.sock mount for security
  • Additional safety environment variables
  • Resource limits: 0.5 CPU, 256MB RAM

Network:

• Named network: vpn_network
• Bridge driver for container isolation
• Labeled for media stack

---

3. vault_template.yaml

Services Modified: vault

Key Changes:

• Added dedicated vault_network
• Removed PUID/PGID (not applicable to Vault image)
• Added Vault-specific environment variables:
  • VAULT_LOG_LEVEL: info
  • VAULT_SKIP_VERIFY: "false"
• Comprehensive healthcheck using Vault's health API
• Resource limits: 1 CPU, 512MB RAM
• Longer start_period (60s) for Vault initialization
• Security hardening with no-new-privileges
• Labeled as security stack

Example Healthcheck:

healthcheck:
  test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider https://localhost:8200/v1/sys/health || exit 1"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 60s

---

Resource Allocation Guide

The following table shows the resource allocations for each service:

Service	CPU Limit	Memory Limit	CPU Reserve	Memory Reserve
postgres	2.0	2G	0.5	512M
pgadmin	1.0	1G	0.25	256M
gluetun	1.0	512M	0.25	128M
qbittorrent	2.0	1G	0.5	256M
flaresolverr	1.0	1G	0.25	256M
sabnzbd	2.0	2G	0.5	512M
prowlarr	1.0	512M	0.25	128M
radarr	1.0	1G	0.25	256M
sonarr	1.0	1G	0.25	256M
bazarr	0.5	512M	0.1	128M
emby	4.0	4G	1.0	1G
jellyseerr	0.5	512M	0.1	128M
recyclarr	0.5	256M	0.1	64M
watchtower	0.5	256M	0.1	64M
vault	1.0	512M	0.25	128M

Total Resources (if all services running):

• Total CPU Limit: 19.5 cores
• Total Memory Limit: 18.75GB
• Total CPU Reserved: 4.6 cores
• Total Memory Reserved: 4.44GB

---

Security Improvements

1. Privilege Escalation Prevention

   • All services have no-new-privileges:true security option
   • Prevents containers from gaining additional privileges

2. Read-Only Mounts

   • Docker socket mounted read-only in Watchtower
   • /etc/localtime always mounted read-only
   • Reduces attack surface

3. Network Isolation

   • Separate networks for different stacks:
     • postgres_network - Database services
     • vpn_network - Media services
     • vault_network - Secrets management
   • Services only communicate within their network

4. Resource Limits

   • Prevents DoS through resource exhaustion
   • Ensures critical services always have resources available

---

Healthcheck Strategy

All healthchecks follow this pattern:

healthcheck:
  test: [appropriate health test command]
  interval: 30s       # How often to check (10-60s typical)
  timeout: 10s        # Max time for check to complete
  retries: 3          # Failed checks before unhealthy
  start_period: 30-90s # Grace period for service startup

Start Period Guidelines:

• Simple services: 30s (e.g., FlareSolverr)
• Database services: 30-60s (e.g., Postgres)
• Arr services: 60s (database initialization)
• Media servers: 90s (library scanning)

---

Migration Guide

Before Applying Changes

1. Backup Current Configuration

   cp .env .env.backup
   tar -czf docker-configs-backup.tar.gz docker-compose-files/
   

2. Stop All Services

   docker-compose down
   

3. Generate New Compose Files

   ./substitute_env.sh docker-compose-files/postgres_template.yaml docker-compose.postgres.yml
   ./substitute_env.sh docker-compose-files/arr-stack_template.yaml docker-compose.arr-stack.yml
   ./substitute_env.sh docker-compose-files/vault_template.yaml docker-compose.vault.yml
   

4. Validate Compose Files

   docker-compose -f docker-compose.postgres.yml config
   docker-compose -f docker-compose.arr-stack.yml config
   docker-compose -f docker-compose.vault.yml config
   

5. Start Services Gradually

   # Start VPN first
   docker-compose -f docker-compose.arr-stack.yml up -d gluetun
   
   # Wait for VPN to be healthy, then start download clients
   docker-compose -f docker-compose.arr-stack.yml up -d qbittorrent sabnzbd flaresolverr
   
   # Then start Arr stack
   docker-compose -f docker-compose.arr-stack.yml up -d prowlarr radarr sonarr bazarr
   
   # Finally media server and supporting services
   docker-compose -f docker-compose.arr-stack.yml up -d emby jellyseerr recyclarr watchtower
   

Monitoring Health

Check service health status:

docker ps --format "table {{.Names}}\t{{.Status}}"

View service logs:

docker logs -f <container_name>

Check resource usage:

docker stats

---

Environment Variables

No new environment variables were added. All improvements use existing variables from .env.sample:

• TZ
• PUID/PGID
• DOCKERCONFDIR
• DOCKERSTORAGEDIR
• DOCKERLOGGING_MAXFILE
• DOCKERLOGGING_MAXSIZE
• Service-specific variables (VPN, database credentials, etc.)

---

Compatibility Notes

1. Docker Compose Version

   • Requires Docker Compose v1.27.0+ for v3.8 support
   • All features compatible with Synology DSM 7.x

2. Synology DSM

   • Labels follow Synology conventions
   • Resource limits work with DSM's Docker implementation
   • Healthchecks supported in DSM 7.x

3. Backward Compatibility

   • Environment variables unchanged - no .env modifications needed
   • Volume paths unchanged - existing data safe
   • Port mappings unchanged - no networking changes required

---

Troubleshooting

Services Won't Start

• Check docker logs <container> for errors
• Verify healthchecks aren't too aggressive
• Ensure sufficient system resources available

Healthcheck Failures

• Increase start_period if service needs more init time
• Check healthcheck command syntax
• Verify service actually provides the expected endpoint

Resource Constraints

• Adjust limits in templates based on your hardware
• Monitor with docker stats
• Consider running fewer services simultaneously

Dependency Issues

• Verify dependent services are healthy: docker ps
• Check that networks are created correctly
• Review service startup order

---

Future Improvements

Potential enhancements for consideration:

1. Secrets Management

   • Integrate Docker secrets for sensitive values
   • Use Vault for dynamic secrets

2. Monitoring

   • Add Prometheus exporters
   • Implement Grafana dashboards

3. Backup Automation

   • Automated backup containers
   • Volume snapshot integration

4. High Availability

   • Database replication
   • Load balancing for media servers

---

References

• Docker Compose v3 Reference
• Docker Security Best Practices
• Synology Docker Documentation
• TRaSH Guides

---

Last Updated: 2025-11-23 Author: Claude AI Assistant Version: 1.0