feat: [#28] Phase 4 - Hetzner Cloud Provider Implementation

.yamllint-ci.yml

@@ -2,6 +2,7 @@ extends: default
 
 ignore: |
   application/storage/
+  application/config
 
 rules:
   line-length:

Makefile

@@ -1,20 +1,40 @@
 # Makefile for Torrust Tracker Demo - Twelve-Factor App Deployment
 .PHONY: help install-deps test-e2e lint test-unit clean
 .PHONY: infra-init infra-plan infra-apply infra-destroy infra-status infra-refresh-state
-.PHONY: infra-config-local infra-config-production infra-validate-config
+.PHONY: infra-config infra-validate-config
 .PHONY: infra-test-prereq infra-test-ci infra-test-local
-.PHONY: app-deploy app-redeploy app-health-check
+.PHONY: infra-providers infra-environments provider-info
+.PHONY: app-config app-validate-config app-deploy app-redeploy app-health-check
 .PHONY: app-test-config app-test-containers app-test-services
 .PHONY: vm-ssh vm-console vm-gui-console vm-clean-ssh vm-prepare-ssh vm-status
 .PHONY: dev-setup dev-deploy dev-test dev-clean
 
-# Default variables
-VM_NAME ?= torrust-tracker-demo
-ENVIRONMENT ?= local
-TERRAFORM_DIR = infrastructure/terraform
+# Default environment variables
+ENVIRONMENT_TYPE ?= development
+ENVIRONMENT_FILE ?= development-libvirt
+
+# Directory paths
 INFRA_TESTS_DIR = infrastructure/tests
-TESTS_DIR = tests
 SCRIPTS_DIR = infrastructure/scripts
+TERRAFORM_DIR = infrastructure/terraform
+
+# Default target - show help when no target specified
+.DEFAULT_GOAL := help
+
+# Parameter validation target
+check-infra-params:
+	@if [ -z "$(ENVIRONMENT_TYPE)" ]; then \
+		echo "❌ Error: ENVIRONMENT_TYPE not specified"; \
+		echo "Usage: make <target> ENVIRONMENT_TYPE=<type> ENVIRONMENT_FILE=<file>"; \
+		echo "Available environment types: development, testing, e2e, staging, production"; \
+		exit 1; \
+	fi
+	@if [ -z "$(ENVIRONMENT_FILE)" ]; then \
+		echo "❌ Error: ENVIRONMENT_FILE not specified"; \
+		echo "Usage: make <target> ENVIRONMENT_TYPE=<type> ENVIRONMENT_FILE=<file>"; \
+		echo "Example: make infra-apply ENVIRONMENT_TYPE=development ENVIRONMENT_FILE=development-libvirt"; \
+		exit 1; \
+	fi
 
 # Help target
 help: ## Show this help message
@@ -43,10 +63,21 @@ help: ## Show this help message
 	@echo "⚙️  SYSTEM SETUP:"
 	@awk 'BEGIN {FS = ":.*?## "} /^(install-deps|clean).*:.*?## / {printf "  %-20s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
 	@echo ""
-	@echo "Examples:"
-	@echo "  make dev-deploy ENVIRONMENT=local"
-	@echo "  make infra-apply ENVIRONMENT=local"
-	@echo "  make app-deploy ENVIRONMENT=local"
+	@echo "Development examples:"
+	@echo "  make dev-deploy                                    # Uses defaults: development + libvirt"
+	@echo "  make infra-apply ENVIRONMENT_TYPE=development ENVIRONMENT_FILE=development-libvirt"
+	@echo "  make infra-apply ENVIRONMENT_TYPE=production ENVIRONMENT_FILE=production-hetzner"
+	@echo "  make app-deploy ENVIRONMENT_TYPE=development ENVIRONMENT_FILE=development-libvirt"
+	@echo ""
+	@echo "Enhanced Configuration Workflow (Phases 1-6 Completed):"
+	@echo "  make infra-config ENVIRONMENT_TYPE=development PROVIDER=libvirt    # Generate development-libvirt.env"
+	@echo "  make infra-validate-config ENVIRONMENT_FILE=development-libvirt    # Validate infrastructure config"
+	@echo "  make app-config ENVIRONMENT_FILE=development-libvirt               # Generate application configs"
+	@echo "  make app-validate-config ENVIRONMENT_FILE=development-libvirt      # Validate application configs"
+	@echo ""
+	@echo "Complete Deployment Workflow:"
+	@echo "  make infra-apply ENVIRONMENT_TYPE=development ENVIRONMENT_FILE=development-libvirt  # Build stage"
+	@echo "  make app-deploy ENVIRONMENT_TYPE=development ENVIRONMENT_FILE=development-libvirt   # Release + Run stages"
 
 install-deps: ## Install required dependencies (Ubuntu/Debian)
 	@echo "Installing dependencies..."
@@ -60,47 +91,125 @@ install-deps: ## Install required dependencies (Ubuntu/Debian)
 # INFRASTRUCTURE LAYER (PLATFORM SETUP & CONFIGURATION)
 # =============================================================================
 
-infra-init: ## Initialize infrastructure (Terraform init)
-	@echo "Initializing infrastructure for $(ENVIRONMENT)..."
-	$(SCRIPTS_DIR)/provision-infrastructure.sh $(ENVIRONMENT) init
+infra-init: check-infra-params ## Initialize infrastructure (Terraform init)
+	@echo "Initializing infrastructure with environment file: $(ENVIRONMENT_FILE)"
+	ENVIRONMENT_TYPE=$(ENVIRONMENT_TYPE) ENVIRONMENT_FILE=$(ENVIRONMENT_FILE) $(SCRIPTS_DIR)/provision-infrastructure.sh init
 
-infra-plan: ## Plan infrastructure changes
-	@echo "Planning infrastructure for $(ENVIRONMENT)..."
-	$(SCRIPTS_DIR)/provision-infrastructure.sh $(ENVIRONMENT) plan
+infra-plan: check-infra-params ## Plan infrastructure changes
+	@echo "Planning infrastructure with environment file: $(ENVIRONMENT_FILE)"
+	ENVIRONMENT_TYPE=$(ENVIRONMENT_TYPE) ENVIRONMENT_FILE=$(ENVIRONMENT_FILE) $(SCRIPTS_DIR)/provision-infrastructure.sh plan
 
-infra-apply: ## Provision infrastructure (platform setup)
-	@echo "Provisioning infrastructure for $(ENVIRONMENT)..."
+infra-apply: check-infra-params ## Provision infrastructure (platform setup)
+	@echo "Provisioning infrastructure with environment file: $(ENVIRONMENT_FILE)"
 	@echo "⚠️  This command may prompt for your password for sudo operations"
 	@if [ "$(SKIP_WAIT)" = "true" ]; then \
 		echo "⚠️  SKIP_WAIT=true - Infrastructure will not wait for full readiness"; \
 	else \
 		echo "ℹ️  Infrastructure will wait for full readiness (use SKIP_WAIT=true to skip)"; \
 	fi
-	SKIP_WAIT=$(SKIP_WAIT) $(SCRIPTS_DIR)/provision-infrastructure.sh $(ENVIRONMENT) apply
+	SKIP_WAIT=$(SKIP_WAIT) ENVIRONMENT_TYPE=$(ENVIRONMENT_TYPE) ENVIRONMENT_FILE=$(ENVIRONMENT_FILE) $(SCRIPTS_DIR)/provision-infrastructure.sh apply
 
-infra-destroy: ## Destroy infrastructure
-	@echo "Destroying infrastructure for $(ENVIRONMENT)..."
-	$(SCRIPTS_DIR)/provision-infrastructure.sh $(ENVIRONMENT) destroy
+infra-destroy: check-infra-params ## Destroy infrastructure
+	@echo "Destroying infrastructure with environment file: $(ENVIRONMENT_FILE)"
+	ENVIRONMENT_TYPE=$(ENVIRONMENT_TYPE) ENVIRONMENT_FILE=$(ENVIRONMENT_FILE) $(SCRIPTS_DIR)/provision-infrastructure.sh destroy
 
 infra-status: ## Show infrastructure status
-	@echo "Infrastructure status for $(ENVIRONMENT):"
+	@echo "Infrastructure status:"
 	@cd $(TERRAFORM_DIR) && tofu show -no-color | grep -E "(vm_ip|vm_status)" || echo "No infrastructure found"
 
-infra-refresh-state: ## Refresh Terraform state to detect IP changes
+infra-refresh-state: check-infra-params ## Refresh Terraform state to detect IP changes
 	@echo "Refreshing Terraform state..."
 	@cd $(TERRAFORM_DIR) && tofu refresh
 
-infra-config-local: ## Generate local environment configuration
-	@echo "Configuring local environment..."
-	$(SCRIPTS_DIR)/configure-env.sh local
+# Provider and environment information
+infra-providers: ## List available infrastructure providers
+	@echo "Available Infrastructure Providers:"
+	@echo "Templates (infrastructure/config/templates/providers/):"
+	@ls infrastructure/config/templates/providers/*.env.tpl 2>/dev/null | \
+		xargs -I {} basename {} | sed 's/\.env.*//g' | sort | uniq || \
+		echo "  No templates found"
+	@echo ""
+	@echo "User configurations (infrastructure/config/providers/):"
+	@ls infrastructure/config/providers/*.env 2>/dev/null | \
+		xargs -I {} basename {} | sed 's/\.env.*//g' | sort | uniq || \
+		echo "  No user configs found"
+	@echo ""
+	@echo "Provider types:"
+	@echo "  libvirt - Local KVM/libvirt virtualization for development"
+	@echo "  hetzner - Hetzner Cloud for production deployments"
+	@echo ""
+	@echo "Usage examples:"
+	@echo "  make infra-apply ENVIRONMENT_TYPE=development ENVIRONMENT_FILE=development-libvirt"
+	@echo "  make infra-apply ENVIRONMENT_TYPE=staging ENVIRONMENT_FILE=staging-digitalocean"
+	@echo "  make infra-apply ENVIRONMENT_TYPE=production ENVIRONMENT_FILE=production-hetzner"
 
-infra-config-production: ## Generate production environment configuration
-	@echo "Configuring production environment..."
-	$(SCRIPTS_DIR)/configure-env.sh production
+infra-environments: ## List available environments and their providers
+	@echo "Available Environment Configurations:"
+	@echo ""
+	@echo "Templates (infrastructure/config/templates/environments/):"
+	@ls infrastructure/config/templates/environments/*.defaults 2>/dev/null | \
+		xargs -I {} basename {} .defaults | sort | sed 's/^/  /' || \
+		echo "  No template defaults found"
+	@echo ""
+	@echo "User configurations (infrastructure/config/environments/):"
+	@if ls infrastructure/config/environments/*.env >/dev/null 2>&1; then \
+		for file in infrastructure/config/environments/*.env; do \
+			if [ -f "$$file" ]; then \
+				env=$$(grep "^ENVIRONMENT_TYPE=" "$$file" 2>/dev/null | cut -d'=' -f2 | tr -d '"' | tr -d "'"); \
+				provider=$$(grep "^PROVIDER=" "$$file" 2>/dev/null | cut -d'=' -f2 | tr -d '"' | tr -d "'"); \
+				filename=$$(basename "$$file" .env); \
+				echo "  $$filename -> Environment: $$env, Provider: $$provider"; \
+			fi \
+		done; \
+	else \
+		echo "  No user configs found"; \
+	fi
+	@echo ""
+	@echo "Environment types:"
+	@echo "  development - Local development and testing"
+	@echo "  testing     - General testing (reserved for future use)"
+	@echo "  e2e         - End-to-end testing"
+	@echo "  staging     - Pre-production testing"
+	@echo "  production  - Production deployment"
+	@echo ""
+	@echo "Usage examples:"
+	@echo "  make infra-config ENVIRONMENT_TYPE=development PROVIDER=libvirt   # Create development-libvirt.env"
+	@echo "  make infra-config ENVIRONMENT_TYPE=production PROVIDER=hetzner    # Create production-hetzner.env"
+	@echo "  make infra-apply ENVIRONMENT_TYPE=development ENVIRONMENT_FILE=development-libvirt"
+	@echo "  make infra-apply ENVIRONMENT_TYPE=production ENVIRONMENT_FILE=production-hetzner"
+
+provider-info: ## Show provider information (requires PROVIDER=<name>)
+	@if [ -z "$(PROVIDER)" ]; then \
+		echo "Error: PROVIDER not specified"; \
+		echo "Usage: make provider-info PROVIDER=<provider>"; \
+		exit 1; \
+	fi
+	@echo "Getting information for provider: $(PROVIDER)"
+	@$(SCRIPTS_DIR)/providers/provider-interface.sh info $(PROVIDER)
+
+infra-config: ## Generate environment configuration (requires ENVIRONMENT_TYPE and PROVIDER)
+	@if [ -z "$(ENVIRONMENT_TYPE)" ]; then \
+		echo "Error: ENVIRONMENT_TYPE not specified"; \
+		echo "Usage: make infra-config ENVIRONMENT_TYPE=<type> PROVIDER=<provider>"; \
+		echo "Available environment types: development, testing, e2e, staging, production"; \
+		echo "Available providers: libvirt, hetzner"; \
+		echo "Example: make infra-config ENVIRONMENT_TYPE=development PROVIDER=libvirt"; \
+		exit 1; \
+	fi
+	@if [ -z "$(PROVIDER)" ]; then \
+		echo "Error: PROVIDER not specified"; \
+		echo "Usage: make infra-config ENVIRONMENT_TYPE=<type> PROVIDER=<provider>"; \
+		echo "Available environment types: development, testing, e2e, staging, production"; \
+		echo "Available providers: libvirt, hetzner"; \
+		echo "Example: make infra-config ENVIRONMENT_TYPE=development PROVIDER=libvirt"; \
+		exit 1; \
+	fi
+	@echo "Configuring $(ENVIRONMENT_TYPE) environment for $(PROVIDER)..."
+	$(SCRIPTS_DIR)/configure-env.sh $(ENVIRONMENT_TYPE) $(PROVIDER)
 
 infra-validate-config: ## Validate configuration for all environments
 	@echo "Validating configuration..."
-	$(SCRIPTS_DIR)/validate-config.sh
+	$(SCRIPTS_DIR)/validate-config.sh $(ENVIRONMENT_FILE)
 
 infra-test-prereq: ## Test system prerequisites for development
 	@echo "Testing prerequisites..."
@@ -119,22 +228,46 @@ infra-test-local: ## Run local-only infrastructure tests (requires virtualizatio
 # APPLICATION LAYER (BUILD + RELEASE + RUN STAGES)
 # =============================================================================
 
+app-config: ## Generate application configuration for environment (Release stage preparation)
+	@echo "Generating application configuration for environment: $(ENVIRONMENT_FILE)..."
+	@if [ -z "$(ENVIRONMENT_FILE)" ]; then \
+		echo "❌ Error: ENVIRONMENT_FILE parameter is required"; \
+		echo "Usage: make app-config ENVIRONMENT_FILE=staging-hetzner"; \
+		echo "Available environments:"; \
+		ls infrastructure/config/environments/*.env 2>/dev/null | \
+			xargs -I {} basename {} .env | sed 's/^/  /' || \
+			echo "  No environments found - generate with make infra-config"; \
+		exit 1; \
+	fi
+	application/scripts/configure-app.sh $(ENVIRONMENT_FILE)
+
+app-validate-config: ## Validate application configuration for environment
+	@echo "Validating application configuration for environment: $(ENVIRONMENT_FILE)..."
+	@if [ -z "$(ENVIRONMENT_FILE)" ]; then \
+		echo "❌ Error: ENVIRONMENT_FILE parameter is required"; \
+		echo "Usage: make app-validate-config ENVIRONMENT_FILE=staging-hetzner"; \
+		echo "Available environments:"; \
+		find infrastructure/config/environments/ -name "*.env" -exec basename {} .env \; 2>/dev/null | sort || true; \
+		exit 1; \
+	fi
+	application/scripts/configure-app.sh --validate $(ENVIRONMENT_FILE)
+
 app-deploy: ## Deploy application (Twelve-Factor Build + Release + Run stages)
-	@echo "Deploying application for $(ENVIRONMENT)..."
+	@echo "Deploying application for $(ENVIRONMENT_TYPE)-$(ENVIRONMENT_FILE)..."
 	@if [ "$(SKIP_WAIT)" = "true" ]; then \
 		echo "⚠️  SKIP_WAIT=true - Application will not wait for service readiness"; \
 	else \
 		echo "ℹ️  Application will wait for service readiness (use SKIP_WAIT=true to skip)"; \
 	fi
-	SKIP_WAIT=$(SKIP_WAIT) $(SCRIPTS_DIR)/deploy-app.sh $(ENVIRONMENT)
+	SKIP_WAIT=$(SKIP_WAIT) ENVIRONMENT_TYPE=$(ENVIRONMENT_TYPE) ENVIRONMENT_FILE=$(ENVIRONMENT_FILE) $(SCRIPTS_DIR)/deploy-app.sh $(ENVIRONMENT_TYPE)-$(ENVIRONMENT_FILE)
 
 app-redeploy: ## Redeploy application without infrastructure changes
-	@echo "Redeploying application for $(ENVIRONMENT)..."
-	$(SCRIPTS_DIR)/deploy-app.sh $(ENVIRONMENT)
+	@echo "Redeploying application for $(ENVIRONMENT_TYPE)-$(ENVIRONMENT_FILE)..."
+	ENVIRONMENT_TYPE=$(ENVIRONMENT_TYPE) ENVIRONMENT_FILE=$(ENVIRONMENT_FILE) $(SCRIPTS_DIR)/deploy-app.sh $(ENVIRONMENT_TYPE)-$(ENVIRONMENT_FILE)
 
 app-health-check: ## Validate deployment health
-	@echo "Running health check for $(ENVIRONMENT)..."
-	$(SCRIPTS_DIR)/health-check.sh $(ENVIRONMENT)
+	@echo "Running health check for environment type: $(ENVIRONMENT_TYPE), environment file: $(ENVIRONMENT_FILE)..."
+	ENVIRONMENT_TYPE=$(ENVIRONMENT_TYPE) ENVIRONMENT_FILE=$(ENVIRONMENT_FILE) $(SCRIPTS_DIR)/health-check.sh $(ENVIRONMENT_TYPE)-$(ENVIRONMENT_FILE)
 
 app-test-config: ## Test application configuration
 	@echo "Testing application configuration..."
@@ -203,10 +336,10 @@ dev-setup: ## Complete development setup
 	@make install-deps
 
 dev-deploy: ## Full deployment workflow (infra + app)
-	@echo "Running full deployment workflow for $(ENVIRONMENT)..."
-	@make infra-apply ENVIRONMENT=$(ENVIRONMENT)
-	@make app-deploy ENVIRONMENT=$(ENVIRONMENT)
-	@make app-health-check ENVIRONMENT=$(ENVIRONMENT)
+	@echo "Running full deployment workflow for $(DEV_ENVIRONMENT) with $(DEV_PROVIDER)..."
+	@make infra-apply ENVIRONMENT=$(DEV_ENVIRONMENT) PROVIDER=$(DEV_PROVIDER)
+	@make app-deploy ENVIRONMENT=$(DEV_ENVIRONMENT)
+	@make app-health-check ENVIRONMENT=$(DEV_ENVIRONMENT)
 	@echo "✅ Development deployment complete"
 
 dev-test: ## Quick validation (syntax + unit tests)
@@ -217,7 +350,7 @@ dev-test: ## Quick validation (syntax + unit tests)
 
 dev-clean: ## Complete cleanup
 	@echo "Cleaning up development environment..."
-	@make infra-destroy ENVIRONMENT=$(ENVIRONMENT) || true
+	@make infra-destroy ENVIRONMENT=$(DEV_ENVIRONMENT) PROVIDER=$(DEV_PROVIDER) || true
 	@make clean
 	@echo "✅ Development environment cleaned"
 
@@ -227,7 +360,7 @@ dev-clean: ## Complete cleanup
 
 test-e2e: ## Run comprehensive end-to-end test (follows integration guide)
 	@echo "Running comprehensive end-to-end test..."
-	$(TESTS_DIR)/test-e2e.sh $(ENVIRONMENT)
+	$(TESTS_DIR)/test-e2e.sh $(DEV_ENVIRONMENT)
 
 test-ci: ## Run project-wide CI tests (global concerns)
 	@echo "Running project-wide CI tests..."

README.md

@@ -150,7 +150,7 @@ peer connections, and system health.
 
 ## 🚀 Quick Start
 
-**New users start here**: [**Deployment Guide**](docs/guides/cloud-deployment-guide.md) -
+**New users start here**: [**Deployment Guide**](docs/guides/deployment-guide.md) -
 Complete guide for deploying Torrust Tracker locally or in the cloud
 
 For detailed setup instructions, see the specific documentation:
@@ -211,7 +211,7 @@ make dev-deploy ENVIRONMENT=local      # Does all steps 3-4
 
 ### General Documentation
 
-- [Deployment Guide](docs/guides/cloud-deployment-guide.md) - **Main deployment
+- [Deployment Guide](docs/guides/deployment-guide.md) - **Main deployment
   guide** for local development and planned cloud deployment
 - [Documentation Structure](docs/README.md) - Cross-cutting documentation
 - [Architecture Decisions](docs/adr/) - Design decisions and rationale

application/.gitignore

@@ -21,6 +21,9 @@ docker-compose.override.yml
 *.sqlite
 *.sqlite3
 
+# Generated configuration files (per-environment)
+/config/
+
 # SSL certificates and keys
 /ssl/
 /certs/

application/README.md

@@ -24,11 +24,6 @@ application/
 │   │   ├── time-running.sh
 │   │   ├── tracker-db-backup.sh
 │   │   └── tracker-filtered-logs.sh
-│   ├── container/default/config/  # Container configurations
-│   │   ├── crontab.conf
-│   │   ├── nginx.conf
-│   │   ├── prometheus.yml
-│   │   └── tracker.prod.container.sqlite3.toml
 │   ├── dev/home/             # Development configurations
 │   └── grafana/dashboards/   # Grafana dashboard configurations
 │       ├── metrics.json

application/docs/backups.md

@@ -13,9 +13,8 @@ cd /home/torrust/github/torrust/torrust-tracker-demo/
 sudo crontab -e
 ```
 
-You should see the
-[crontab.conf](../share/container/default/config/crontab.conf) configuration
-file.
+You should see the MySQL backup cron job configured from the template system in
+`infrastructure/config/templates/application/crontab/mysql-backup.cron.tpl`.
 
 ## Check Backups