feat: Add Makefile, Traefik support, and direnv integration

Added:
- Makefile with convenient commands:
  - make clone-moodle: Clone Moodle (shallow, depth=1, tip only)
  - make setup: Create .env file
  - make start: Start stack
  - make start-traefik: Start with Traefik integration
  - make logs/status/health: Monitoring commands
  - make clean: Cleanup commands

- compose.traefik.yml: Traefik reverse proxy configuration
  - Disables exposed ports
  - Adds Traefik labels for routing
  - Automatic HTTPS with Let's Encrypt
  - HTTP to HTTPS redirect

- .envrc: direnv integration for auto-loading environment
  - Helper function: moodle-help
  - Auto-loads .env when entering directory

- Updated .env.example with Traefik variables:
  - MOODLE_DOMAIN
  - TRAEFIK_NETWORK
  - TRAEFIK_CERTRESOLVER

- Updated README with:
  - Makefile usage (recommended quick start)
  - Traefik integration section
  - Collapsible manual setup instructions

Author: CybotTM

.env.example

@@ -41,10 +41,22 @@ VALKEY_PORT=6379
 # SECURITY: Generate secure password!
 VALKEY_PASSWORD=CHANGE_ME_SECURE_VALKEY_PASSWORD_HERE
 
+# ============================================================================
+# Traefik Configuration (optional - for production with Traefik)
+# ============================================================================
+# Domain for Moodle (used when starting with Traefik)
+MOODLE_DOMAIN=moodle.example.com
+
+# Traefik network name (must exist)
+TRAEFIK_NETWORK=traefik
+
+# TLS certificate resolver configured in Traefik
+TRAEFIK_CERTRESOLVER=letsencrypt
+
 # ============================================================================
 # Notes
 # ============================================================================
 # 1. Never commit .env file to version control (add to .gitignore)
 # 2. Generate strong passwords: openssl rand -base64 32
 # 3. For production, use actual domain in MOODLE_SITE_URL
-# 4. Traefik labels in compose.yml are commented out by default
+# 4. For Traefik mode: use 'make start-traefik' or 'docker compose -f compose.yml -f compose.traefik.yml up -d'

.envrc

@@ -0,0 +1,29 @@
+# direnv configuration for Moodle Docker Stack
+# This file is loaded automatically by direnv when you cd into this directory
+# Install direnv: https://direnv.net/
+
+# Load .env file if it exists
+dotenv_if_exists .env
+
+# Set compose file for Traefik mode (uncomment to enable)
+# export COMPOSE_FILE=compose.yml:compose.traefik.yml
+
+# Helper functions
+function moodle-help() {
+  echo "Moodle Docker Stack - Quick Commands:"
+  echo ""
+  echo "  make help          - Show all available commands"
+  echo "  make clone-moodle  - Clone Moodle repository"
+  echo "  make setup         - Create .env file"
+  echo "  make start         - Start the stack"
+  echo "  make logs          - View logs"
+  echo "  make status        - Check container status"
+  echo ""
+}
+
+# Show help on first load
+if [ -z "$MOODLE_DIRENV_LOADED" ]; then
+  export MOODLE_DIRENV_LOADED=1
+  echo "✅ Moodle Docker environment loaded"
+  echo "   Run 'moodle-help' for available commands"
+fi

.gitignore

@@ -1,5 +1,6 @@
 # Environment configuration (contains secrets)
 .env
+.envrc.local
 
 # Moodle code (managed via git clone separately)
 /moodle/

Makefile

@@ -0,0 +1,140 @@
+.PHONY: help clone-moodle setup start stop restart logs clean build traefik
+
+# Default target
+.DEFAULT_GOAL := help
+
+# Variables
+MOODLE_BRANCH ?= MOODLE_405_STABLE
+COMPOSE_FILES := -f compose.yml
+COMPOSE_TRAEFIK := -f compose.yml -f compose.traefik.yml
+
+help: ## Show this help message
+	@echo "Moodle Docker Stack - Available commands:"
+	@echo ""
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo ""
+	@echo "Quick start:"
+	@echo "  1. make clone-moodle   # Clone Moodle code"
+	@echo "  2. make setup          # Create .env file"
+	@echo "  3. make start          # Start the stack"
+	@echo ""
+
+clone-moodle: ## Clone Moodle repository (shallow clone, tip only)
+	@if [ -d "moodle" ]; then \
+		echo "⚠️  Moodle directory already exists"; \
+		read -p "Delete and re-clone? [y/N] " confirm; \
+		if [ "$$confirm" = "y" ] || [ "$$confirm" = "Y" ]; then \
+			rm -rf moodle; \
+		else \
+			echo "Aborted."; \
+			exit 1; \
+		fi; \
+	fi
+	@echo "📥 Cloning Moodle $(MOODLE_BRANCH) (depth=1)..."
+	git clone -b $(MOODLE_BRANCH) --depth 1 git://git.moodle.org/moodle.git
+	@cd moodle && git branch
+	@echo "✅ Moodle cloned successfully"
+
+setup: ## Create .env file from template
+	@if [ -f ".env" ]; then \
+		echo "⚠️  .env file already exists"; \
+		read -p "Overwrite? [y/N] " confirm; \
+		if [ "$$confirm" != "y" ] && [ "$$confirm" != "Y" ]; then \
+			echo "Aborted."; \
+			exit 1; \
+		fi; \
+	fi
+	cp .env.example .env
+	@echo "⚠️  IMPORTANT: Edit .env and set secure passwords!"
+	@echo "   Required: DB_PASSWORD, DB_ROOT_PASSWORD, VALKEY_PASSWORD"
+
+start: ## Start all services (pulls pre-built image)
+	docker compose $(COMPOSE_FILES) up -d
+	@echo ""
+	@echo "✅ Stack started!"
+	@echo "   Moodle: http://localhost:8080"
+	@echo ""
+	@echo "Check status: make status"
+	@echo "View logs:    make logs"
+
+start-traefik: ## Start with Traefik (no exposed ports, uses Traefik labels)
+	docker compose $(COMPOSE_TRAEFIK) up -d
+	@echo ""
+	@echo "✅ Stack started with Traefik!"
+	@echo "   Access via your configured Traefik domain"
+	@echo ""
+	@echo "Check status: make status"
+
+stop: ## Stop all services
+	docker compose $(COMPOSE_FILES) down
+	@echo "✅ Stack stopped"
+
+restart: ## Restart all services
+	docker compose $(COMPOSE_FILES) restart
+	@echo "✅ Stack restarted"
+
+build: ## Build Moodle image locally
+	docker compose $(COMPOSE_FILES) build
+	@echo "✅ Image built"
+
+logs: ## Show logs from all services
+	docker compose $(COMPOSE_FILES) logs -f
+
+logs-moodle: ## Show Moodle logs only
+	docker compose $(COMPOSE_FILES) logs -f moodle
+
+logs-db: ## Show database logs only
+	docker compose $(COMPOSE_FILES) logs -f database
+
+logs-valkey: ## Show Valkey logs only
+	docker compose $(COMPOSE_FILES) logs -f valkey
+
+logs-ofelia: ## Show Ofelia cron logs only
+	docker compose $(COMPOSE_FILES) logs -f ofelia
+
+status: ## Show container status
+	docker compose $(COMPOSE_FILES) ps
+
+health: ## Check service health
+	@echo "=== Service Health Status ==="
+	@docker compose $(COMPOSE_FILES) ps --format "table {{.Name}}\t{{.Status}}\t{{.Health}}"
+
+shell-moodle: ## Open shell in Moodle container
+	docker compose $(COMPOSE_FILES) exec moodle bash
+
+shell-db: ## Open MariaDB shell
+	docker compose $(COMPOSE_FILES) exec database mariadb -uroot -p
+
+clean: ## Stop and remove all containers, volumes, and networks
+	@echo "⚠️  This will remove all containers, volumes, and data!"
+	@read -p "Continue? [y/N] " confirm; \
+	if [ "$$confirm" = "y" ] || [ "$$confirm" = "Y" ]; then \
+		docker compose $(COMPOSE_FILES) down -v; \
+		echo "✅ Stack cleaned"; \
+	else \
+		echo "Aborted."; \
+	fi
+
+clean-moodle: ## Remove Moodle clone directory
+	@echo "⚠️  This will delete the moodle/ directory!"
+	@read -p "Continue? [y/N] " confirm; \
+	if [ "$$confirm" = "y" ] || [ "$$confirm" = "Y" ]; then \
+		rm -rf moodle; \
+		echo "✅ Moodle directory removed"; \
+	else \
+		echo "Aborted."; \
+	fi
+
+pull: ## Pull latest pre-built image from GHCR
+	docker compose $(COMPOSE_FILES) pull moodle
+	@echo "✅ Latest image pulled"
+
+upgrade-moodle: ## Upgrade Moodle code to latest in branch
+	@if [ ! -d "moodle" ]; then \
+		echo "❌ Moodle directory not found. Run 'make clone-moodle' first."; \
+		exit 1; \
+	fi
+	@echo "📥 Pulling latest Moodle updates..."
+	cd moodle && git pull
+	@echo "✅ Moodle updated"
+	@echo "⚠️  Remember to run the Moodle upgrade: http://localhost:8080/admin"

README.md

@@ -70,20 +70,39 @@ The `compose.yml` includes both `image:` and `build:` directives:
 
 ## Quick Start
 
-### 1. Clone Moodle Repository
+### Using Makefile (Recommended)
 
 ```bash
-# Clone Moodle 4.5 stable branch
-git clone -b MOODLE_405_STABLE --depth 1 git://git.moodle.org/moodle.git
+# 1. Clone Moodle code
+make clone-moodle
 
-# Verify branch
-cd moodle
-git branch
-# Should show: * MOODLE_405_STABLE
-cd ..
+# 2. Create .env file
+make setup
+# Edit .env and set secure passwords!
+
+# 3. Start the stack
+make start
+
+# Check status
+make status
+
+# View all available commands
+make help
+```
+
+### Manual Setup
+
+<details>
+<summary>Click to expand manual setup instructions</summary>
+
+#### 1. Clone Moodle Repository
+
+```bash
+# Clone Moodle 4.5 stable branch (shallow clone)
+git clone -b MOODLE_405_STABLE --depth 1 git://git.moodle.org/moodle.git
 ```
 
-### 2. Configure Environment
+#### 2. Configure Environment
 
 ```bash
 # Copy environment template
@@ -104,7 +123,7 @@ nano .env
 - `VALKEY_PASSWORD`: Set secure password
 - `MOODLE_SITE_URL`: Update for production (e.g., `https://moodle.example.com`)
 
-### 3. Start Services
+#### 3. Start Services
 
 ```bash
 # Pull pre-built image and start all services
@@ -117,6 +136,34 @@ docker compose ps
 docker compose logs -f moodle
 ```
 
+</details>
+
+## Traefik Integration
+
+For production deployments with Traefik reverse proxy:
+
+```bash
+# 1. Configure Traefik variables in .env
+MOODLE_DOMAIN=moodle.example.com
+MOODLE_SITE_URL=https://moodle.example.com
+TRAEFIK_NETWORK=traefik
+TRAEFIK_CERTRESOLVER=letsencrypt
+
+# 2. Start with Traefik
+make start-traefik
+
+# Or manually:
+docker compose -f compose.yml -f compose.traefik.yml up -d
+```
+
+**Traefik features:**
+- ✅ Automatic HTTPS with Let's Encrypt
+- ✅ No exposed ports (Traefik handles routing)
+- ✅ HTTP to HTTPS redirect
+- ✅ Custom domain support
+
+## Installation
+
 ### 4. Install Moodle
 
 **Option A: Web Installer (Recommended)**

compose.traefik.yml

@@ -0,0 +1,50 @@
+# Traefik Override Configuration
+# Usage: docker compose -f compose.yml -f compose.traefik.yml up -d
+# Or: make start-traefik
+
+services:
+  moodle:
+    # Disable direct port exposure (Traefik handles routing)
+    ports: []
+
+    # Enable Traefik labels
+    labels:
+      # Ofelia cron labels (keep these)
+      ofelia.enabled: "true"
+      ofelia.job-exec.moodle-cron.schedule: "@every 1m"
+      ofelia.job-exec.moodle-cron.command: "php /var/www/html/admin/cli/cron.php"
+      ofelia.job-exec.moodle-cron.user: "www-data"
+
+      # Traefik configuration
+      traefik.enable: "true"
+
+      # HTTP router
+      traefik.http.routers.moodle.rule: "Host(`${MOODLE_DOMAIN:-moodle.localhost}`)"
+      traefik.http.routers.moodle.entrypoints: "websecure"
+      traefik.http.routers.moodle.tls: "true"
+      traefik.http.routers.moodle.tls.certresolver: "${TRAEFIK_CERTRESOLVER:-letsencrypt}"
+
+      # Service configuration
+      traefik.http.services.moodle.loadbalancer.server.port: "80"
+
+      # Middleware (optional - uncomment if needed)
+      # traefik.http.routers.moodle.middlewares: "moodle-headers"
+      # traefik.http.middlewares.moodle-headers.headers.customResponseHeaders.X-Frame-Options: "SAMEORIGIN"
+      # traefik.http.middlewares.moodle-headers.headers.customResponseHeaders.X-Content-Type-Options: "nosniff"
+
+      # HTTP to HTTPS redirect
+      traefik.http.routers.moodle-http.rule: "Host(`${MOODLE_DOMAIN:-moodle.localhost}`)"
+      traefik.http.routers.moodle-http.entrypoints: "web"
+      traefik.http.routers.moodle-http.middlewares: "moodle-redirect"
+      traefik.http.middlewares.moodle-redirect.redirectscheme.scheme: "https"
+      traefik.http.middlewares.moodle-redirect.redirectscheme.permanent: "true"
+
+    networks:
+      - frontend
+      - backend
+      - traefik  # Add Traefik network
+
+networks:
+  traefik:
+    external: true
+    name: ${TRAEFIK_NETWORK:-traefik}