feat: update deployment configuration and encrypted env loader

- Update Ansible playbooks and roles for application deployment
- Add new Gitea/Traefik troubleshooting playbooks
- Update Docker Compose configurations (base, local, staging, production)
- Enhance EncryptedEnvLoader with improved error handling
- Add deployment scripts (autossh setup, migration, secret testing)
- Update CI/CD workflows and documentation
- Add Semaphore stack configuration

docker-compose.yml

@@ -1,3 +1,36 @@
+# ⚠️  DEPRECATED - Legacy Docker Compose Configuration ⚠️
+#
+# This file is DEPRECATED and kept ONLY for backward compatibility during migration.
+# ⚠️  DO NOT USE THIS FILE FOR NEW DEPLOYMENTS ⚠️
+#
+# This file will be REMOVED after the migration period (planned: Q2 2025).
+# All developers must migrate to the Base+Override Pattern before then.
+#
+# ✅ PREFERRED: Use Base+Override Pattern:
+#   - docker-compose.base.yml (shared services)
+#   - docker-compose.local.yml (local development overrides)
+#   - docker-compose.staging.yml (staging overrides)
+#   - docker-compose.production.yml (production overrides)
+#
+# 📖 Usage:
+#   Local:      docker compose -f docker-compose.base.yml -f docker-compose.local.yml up
+#   Staging:    docker compose -f docker-compose.base.yml -f docker-compose.staging.yml up
+#   Production: docker compose -f docker-compose.base.yml -f docker-compose.production.yml up
+#
+# 🔗 See deployment/README.md for details on the Base+Override Pattern
+# 🔗 See ENV_SETUP.md for environment configuration guide
+#
+# ⚠️  Migration Required:
+#   1. Create .env.base from .env.example (run: make env-base)
+#   2. Create .env.local for local overrides (run: make env-local)
+#   3. Update all docker compose commands to use Base+Override files
+#   4. Test your local setup before removing this legacy file
+#
+# 📅 Deprecation Timeline:
+#   - Created: Base+Override Pattern introduced
+#   - Planned Removal: Q2 2025 (after all developers have migrated)
+#   - Action Required: Migrate before removal date
+
 services:
   web:
     container_name: web
@@ -30,6 +63,9 @@ services:
     networks:
       - frontend
       - backend
+    # Legacy .env file (Fallback for backward compatibility)
+    # Preferred: Use docker-compose.base.yml + docker-compose.local.yml
+    # See ENV_SETUP.md for new Base+Override Pattern
     env_file:
       - .env
     deploy:
@@ -90,6 +126,8 @@ services:
     networks:
       - backend
       - cache
+    # Legacy .env file (Fallback for backward compatibility)
+    # Preferred: Use docker-compose.base.yml + docker-compose.local.yml
     env_file:
       - .env
     deploy:
@@ -124,6 +162,7 @@ services:
     networks:
       - backend
       - cache
+    # Legacy .env file (Fallback for backward compatibility)
     env_file:
       - .env
     entrypoint: []
@@ -193,6 +232,7 @@ services:
         max-file: "${LOG_MAX_FILE:-2}"
     networks:
       - cache
+    # Legacy .env file (Fallback for backward compatibility)
     env_file:
       - .env
     deploy:
@@ -236,6 +276,7 @@ services:
     networks:
       - backend
       - cache
+    # Legacy .env file (Fallback for backward compatibility)
     env_file:
       - .env
     # Graceful shutdown timeout