From 543763adf6521449b5aa3599fd49cd36aeb79c9f Mon Sep 17 00:00:00 2001
From: ske087 <ske087@media-share.homeserver>
Date: Wed, 16 Jul 2025 17:59:46 -0400
Subject: [PATCH] docs: Add comprehensive comments to docker-compose.yml

- Added detailed explanations for each configuration section
- Documented port mapping and volume mount purposes
- Explained environment variables and health check settings
- Clarified network configuration and container management
- Improved readability for deployment and maintenance
---
 docker-compose.yml | 48 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/docker-compose.yml b/docker-compose.yml
index dcf59d1..a7d1a56 100755
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,32 +1,78 @@
+# Docker Compose configuration for QR Code Manager
+# This file defines the containerized deployment of the QR Code Manager application
 version: '3.8'
 
 services:
   qr-manager:
+    # Build the Docker image from the Dockerfile in the current directory
     build: .
+    
+    # Set a custom container name for easier identification and management
     container_name: qr-code-manager
+    
+    # Automatically restart the container unless explicitly stopped
+    # Options: no, always, unless-stopped, on-failure
     restart: unless-stopped
+    
+    # Port mapping: host_port:container_port
+    # Maps host port 8066 to container port 5000 (where Flask/Gunicorn runs)
+    # Access the app at: http://localhost:8066 or https://your-domain (via reverse proxy)
     ports:
       - "8066:5000"
+    
+    # Load environment variables from .env file
+    # Contains production settings like SECRET_KEY, ADMIN_USERNAME, etc.
     env_file:
       - .env
+    
+    # Additional environment variables set directly in compose
+    # FLASK_ENV=production enables production mode with Gunicorn server
     environment:
       - FLASK_ENV=production
+    
+    # Volume mounts: host_path:container_path
+    # Persist data and files outside the container for backup and updates
     volumes:
-      # Map to specific folders on your host system
+      # QR code images - stores generated PNG files
       - /opt/qr/qr_codes:/app/app/static/qr_codes
+      
+      # Logo files - stores uploaded custom logos for QR codes
       - /opt/qr/logos:/app/app/static/logos
+      
+      # Flask session files - stores user session data
+      # Uses /app/flask_session to avoid permission issues (mapped from /tmp/flask_session in container)
       - /opt/qr/sessions:/app/flask_session
+      
+      # Application data - stores JSON databases (link_pages.json, qr_codes.json, short_urls.json)
       - /opt/qr/persistent:/app/data
+    
+    # Health check configuration - monitors container health
+    # Ensures the application is responding correctly
     healthcheck:
+      # Command to test application health - checks the /health endpoint
       test: ["CMD", "python", "-c", "import requests; requests.get('http://localhost:5000/health')"]
+      
+      # How often to run the health check
       interval: 30s
+      
+      # Maximum time to wait for health check response
       timeout: 10s
+      
+      # Number of consecutive failures before marking as unhealthy
       retries: 3
+      
+      # Grace period before starting health checks (allows app startup time)
       start_period: 10s
+    
+    # Docker labels for metadata and container management
+    # Useful for monitoring, backup scripts, and documentation
     labels:
       - "com.example.description=QR Code Manager Application"
       - "com.example.service=qr-manager"
 
+# Network configuration
+# Creates a custom network for better container isolation and communication
 networks:
   default:
+    # Custom network name for the QR Manager application
     name: qr-manager-network