added deployment configurations

Author: FionaDmello

.env.example

@@ -16,31 +16,48 @@ COMPOSE_PROJECT_NAME=survey-dashboard
 
 # Port the Panel application runs on inside the container
 # Default: 5006 (Panel's default port)
-APP_PORT=5006
+APP_PORT=
 
 # ============================================================================
 # Nginx Configuration
 # ============================================================================
 
 # Port nginx exposes on the host machine
-# Default: 80 (standard HTTP port)
-# Change to 8080 or another port if 80 is already in use
-NGINX_PORT=80
+# Default: 80 (standard HTTP port), 443 (standard HTTPS port)
+# Change to 8080/8443 if 80/443 are already in use
+NGINX_PORT=
 
 # Your domain name
-# In development: Use 'localhost' or your IP address
+# IMPORTANT: For HTTPS to work, this MUST be a real domain that points to your server
+# In development: Use 'localhost' (HTTPS won't work, only HTTP)
 # In production: Use your actual domain (e.g., survey.example.com)
-# This is used in nginx server_name directive
-HOST=localhost
+# This domain is used by:
+#   - nginx-proxy: Routes traffic from this domain to the dashboard
+#   - acme-companion: Requests SSL certificate for this domain from Let's Encrypt
+HOST=
+
+# Path on the domain where the dashboard is accessible
+# If set, the dashboard will ONLY be accessible at this specific path
+# Examples:
+#   - VIRTUAL_PATH=/survey-dashboard → https://your-domain.com/survey-dashboard
+#   - VIRTUAL_PATH=/dashboard → https://your-domain.com/dashboard
+#   - Leave empty for root path → https://your-domain.com/
+# IMPORTANT: Must start with / (forward slash)
+# All other paths on this domain will return 404
+VIRTUAL_PATH=
 
 # ============================================================================
-# Optional: SSL/HTTPS Configuration (for future use)
+# SSL/HTTPS Configuration (Let's Encrypt)
 # ============================================================================
 
-# Uncomment and configure these if you want to enable HTTPS
-# ENABLE_SSL=false
-# SSL_CERT_PATH=/path/to/cert.pem
-# SSL_KEY_PATH=/path/to/key.pem
+# Your email address for Let's Encrypt certificate registration
+# REQUIRED for production HTTPS deployment
+# Let's Encrypt uses this email to:
+#   - Send certificate expiration warnings (if auto-renewal fails)
+#   - Send security notices about your certificates
+#   - Contact you about your Let's Encrypt account
+# Example: admin@example.com or your-email@gmail.com
+LETSENCRYPT_EMAIL=
 
 # ============================================================================
 # Python Configuration

.gitignore

@@ -107,13 +107,17 @@ celerybeat.pid
 
 # Environments
 .env
+.env
 .venv
 env/
 venv/
 ENV/
 env.bak/
 venv.bak/
 
+# Deployment files (may contain sensitive server info)
+DEPLOYMENT.md
+
 # Spyder project settings
 .spyderproject
 .spyproject
@@ -131,3 +135,7 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+
+# Claude
+.claude/

Dockerfile

@@ -39,5 +39,6 @@ USER appuser
 # Expose the application port
 EXPOSE 5006
 
-# Run the application in production mode using the updated script
-CMD ["survey-dashboard", "--production", "--host", "0.0.0.0", "--port", "5006"]
+# Run the application in production mode
+# Use python -m to run the module directly since we installed with --no-root
+CMD ["python", "-m", "survey_dashboard.scripts", "--production", "--host", "0.0.0.0", "--port", "5006"]

docker-compose.yml

@@ -23,39 +23,124 @@ services:
       - PYTHONUNBUFFERED=1
       # Ensures Python output is sent directly to logs (not buffered)
       # Makes 'docker-compose logs' show real-time output
+      - VIRTUAL_HOST=${HOST}
+      # Tells nginx-proxy which domain should route to this container
+      # nginx-proxy watches Docker and auto-configures when it sees this variable
+      - VIRTUAL_PATH=${VIRTUAL_PATH}
+      # Restricts access to only this specific path on the domain
+      # Example: VIRTUAL_PATH=/survey-dashboard means only /survey-dashboard/* is accessible
+      # All other paths on this domain return 404
+      - VIRTUAL_PROTO=http
+      # Protocol nginx-proxy uses to communicate with this container
+      # Uses HTTP inside Docker network (fast, safe), HTTPS for external traffic
+      - LETSENCRYPT_HOST=${HOST}
+      # Tells acme-companion to get SSL certificate for this domain
+      # acme-companion watches Docker and auto-requests certificates when it sees this
+      - LETSENCRYPT_EMAIL=${LETSENCRYPT_EMAIL}
+      # Email for Let's Encrypt certificate notifications
+      # Used for expiry warnings and security notices about your certificates
 
     # Uncomment to mount local code for development
     # volumes:
     #   - ./survey_dashboard:/app/survey_dashboard
 
-  # Nginx reverse proxy container
-  nginx:
-    image: nginx:latest
-    # Uses official nginx image from Docker Hub
-    # No custom build needed - just mount our config
+  # Nginx reverse proxy container with auto-configuration
+  nginx-proxy:
+    container_name: nginx-proxy
+    image: nginxproxy/nginx-proxy:latest
+    # Auto-configuring reverse proxy that watches Docker containers
+    # Automatically generates nginx config based on container environment variables
 
     ports:
       - "80:80"
-      # Maps host port 80 to container port 80
-      # This is the ONLY port exposed to the internet
-      # Users access dashboard via http://yourdomain.com (port 80)
+      # HTTP port - used for ACME challenges and auto-redirect to HTTPS
+      - "443:443"
+      # HTTPS port - secure encrypted connections
 
     volumes:
-      - ./nginx/conf.d:/etc/nginx/conf.d:ro
-      # Mounts our nginx config into the container
-      # :ro = read-only (nginx cannot modify our files)
-      # Changes to config files are reflected immediately
+      # nginx-proxy auto-generates configuration based on container env vars
+      # Custom per-domain configs can be placed in ./nginx/vhost.d/
+      - ./nginx/certs:/etc/nginx/certs:ro
+      # SSL certificates storage (read-only for nginx-proxy)
+      # acme-companion writes certificates here, nginx-proxy reads them
+      - ./nginx/vhost.d:/etc/nginx/vhost.d
+      # Per-domain custom nginx configurations
+      # Files named after domains (e.g., survey.example.com) are included in that domain's config
+      - ./nginx/html:/usr/share/nginx/html
+      # Web root for serving ACME challenge files during Let's Encrypt verification
+      # acme-companion creates challenge files here, nginx-proxy serves them
+      - /var/run/docker.sock:/tmp/docker.sock:ro
+      # Docker socket for auto-discovery of containers
+      # nginx-proxy watches for containers with VIRTUAL_HOST env var
+      # Read-only for security (can observe but not control Docker)
 
     depends_on:
       - dashboard
-      # Ensures dashboard container starts before nginx
-      # Nginx needs dashboard to be available for proxying
+      # Ensures dashboard container starts before nginx-proxy
+      # nginx-proxy needs dashboard to be available for proxying
 
     restart: unless-stopped
     # Same restart policy as dashboard
 
+    labels:
+      - "com.github.jrcs.letsencrypt_nginx_proxy_companion.nginx_proxy=true"
+      # Identifies this container as the nginx instance for acme-companion to manage
+      # acme-companion will reload this container when SSL certificates are updated
+
+  # Let's Encrypt certificate management container
+  letsencrypt:
+    container_name: acme-companion
+    image: nginxproxy/acme-companion
+    # ACME protocol client for automatic Let's Encrypt certificate management
+    # Watches for containers with LETSENCRYPT_HOST environment variable
+
+    environment:
+      - NGINX_PROXY_CONTAINER=nginx-proxy
+      # Tells acme-companion which nginx container to reload when certificates update
+      # Must match the container_name of nginx-proxy service
+      - DEFAULT_EMAIL=${LETSENCRYPT_EMAIL}
+      # Default email for Let's Encrypt certificate registration and notifications
+      # Individual containers can override with their own LETSENCRYPT_EMAIL
+      # Used for certificate expiry warnings and security notices
+
+    volumes:
+      - ./nginx/certs:/etc/nginx/certs:rw
+      # SSL certificates storage (read-write for acme-companion)
+      # acme-companion writes new certificates here, nginx-proxy reads them
+      # Note: :rw (not :ro like nginx-proxy) because acme-companion must write certs
+      - ./nginx/vhost.d:/etc/nginx/vhost.d
+      # Per-domain custom nginx configurations
+      # acme-companion may add temporary configs for ACME challenge handling
+      - ./nginx/html:/usr/share/nginx/html
+      # Web root for ACME challenge files
+      # acme-companion creates challenge files here, nginx-proxy serves them to Let's Encrypt
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      # Docker socket for container discovery and nginx reload
+      # Watches for containers with LETSENCRYPT_HOST environment variable
+      # Sends reload signal to nginx-proxy when certificates update
+      - acme-data:/etc/acme.sh
+      # Named volume for Let's Encrypt account data (NOT a directory)
+      # Stores account credentials, must persist across container restarts
+      # Losing this data means re-registering with Let's Encrypt
+
+    depends_on:
+      - nginx-proxy
+      # Ensures nginx-proxy starts before acme-companion
+      # acme-companion needs nginx-proxy to be running to reload it when certificates update
+
+    restart: unless-stopped
+    # Automatically restart if container crashes
+    # Persists across system reboots unless manually stopped
+    # Critical for certificate renewal - must stay running to renew certs every 90 days
+
 networks:
   default:
     # Docker Compose automatically creates a default network
     # Both containers join this network and can communicate
     # Service names (dashboard, nginx) work as DNS hostnames
+
+volumes:
+  acme-data:
+    # Named volume for Let's Encrypt account credentials
+    # Docker manages this volume's lifecycle (persists across container removals)
+    # Only destroyed if explicitly deleted with: docker volume rm survey-dashboard_acme-data