refactor: [#21] implement single template approach for environment configuration

- Replace dual templates (local.env.tpl, production.env.tpl) with single base.env.tpl
- Add external defaults files (local.defaults, production.defaults) for environment-specific values
- Update configure-env.sh to load defaults from files instead of hardcoded values
- Improve twelve-factor compliance with single source of truth for configuration
- Add generate-secrets command for secure production secret generation
- Update documentation and .gitignore for new file structure
- Benefits: DRY principle, easier maintenance, version-controlled defaults, no sync issues

This addresses the issue where having separate templates could lead to
synchronization bugs when adding new variables to only one template.
All environment variables now exist in one place with environment-specific
values defined in external, version-controlled defaults files.

Author: josecelano

docs/guides/cloud-deployment-guide.md

@@ -332,7 +332,7 @@ make app-deploy ENVIRONMENT=local
 # - HTTP only (no SSL certificates)
 # - Local domain names (tracker.local)
 # - Basic monitoring
-# - SQLite database (for faster setup)
+# - MySQL database (same as production)
 ```
 
 ### Production Environment Setup
@@ -341,53 +341,69 @@ Before deploying to production, you must configure secure secrets and environmen
 
 #### Step 1: Generate Secure Secrets
 
-Production deployment requires several secure random secrets. Generate them using GPG:
+Production deployment requires several secure random secrets. Use the built-in secret generator:
 
 ```bash
-# Generate secure secrets (40 characters each)
-echo "MYSQL_ROOT_PASSWORD=$(gpg --armor --gen-random 1 40)"
-echo "MYSQL_PASSWORD=$(gpg --armor --gen-random 1 40)"
-echo "TRACKER_ADMIN_TOKEN=$(gpg --armor --gen-random 1 40)"
-echo "GF_SECURITY_ADMIN_PASSWORD=$(gpg --armor --gen-random 1 40)"
+# Generate secure secrets using the built-in helper
+./infrastructure/scripts/configure-env.sh generate-secrets
 ```
 
 **Example output**:
 
 ```bash
+=== TORRUST TRACKER PRODUCTION SECRETS ===
+
+Copy these values into: infrastructure/config/environments/production.env
+
+# === GENERATED SECRETS ===
 MYSQL_ROOT_PASSWORD=jcrmbzlGyeP7z53TUQtXmtltMb5TubsIE9e0DPLnS4Ih29JddQw5JA==
 MYSQL_PASSWORD=kLp9nReY4vXqA7mZ8wB3QcG6FsE1oNtH5jUiD2fK0zRyS9CxT8V1Mq==
 TRACKER_ADMIN_TOKEN=nP6rL2gKbY8xW5zA9mQ4jE3vC7sR1tH0oB9fN6dK5uI8eT2yV1nX4q==
 GF_SECURITY_ADMIN_PASSWORD=wQ9tR4nM7bX2zA8kY6pL5sG1oE3vN0cF9eT8jU4dK7hB6rW5iQ2nM==
+
+# === DOMAIN CONFIGURATION (REPLACE WITH YOUR VALUES) ===
+DOMAIN_NAME=your-domain.com
+CERTBOT_EMAIL=admin@your-domain.com
 ```
 
 #### Step 2: Configure Production Environment
 
-Edit the production environment template with your secure secrets:
+**Note**: The project now uses a unified configuration template approach following twelve-factor
+principles. This eliminates synchronization issues between multiple template files.
 
-```bash
-# Copy production template
-cp infrastructure/config/environments/production.env.tpl infrastructure/config/environments/production.env
+Generate the production configuration template:
 
-# Edit with your secure secrets and domain configuration
-vim infrastructure/config/environments/production.env
+```bash
+# Generate production configuration template with placeholders
+make infra-config-production
 ```
 
-**Required Configuration**:
+This will create `infrastructure/config/environments/production.env` with secure placeholder
+values that need to be replaced with your actual configuration.
+
+#### Step 3: Replace Placeholder Values
+
+Edit the generated production environment file with your secure secrets and domain configuration:
 
 ```bash
-# Replace these placeholder values with your actual configuration:
+# Edit the production configuration
+vim infrastructure/config/environments/production.env
+```
 
-# === DOMAIN CONFIGURATION ===
-DOMAIN_NAME=your-domain.com                    # Your actual domain
-CERTBOT_EMAIL=admin@your-domain.com            # Your email for Let's Encrypt
+**Replace these placeholder values with your actual configuration**:
 
+```bash
 # === SECURE SECRETS ===
 # Replace with secrets generated above
 MYSQL_ROOT_PASSWORD=jcrmbzlGyeP7z53TUQtXmtltMb5TubsIE9e0DPLnS4Ih29JddQw5JA==
 MYSQL_PASSWORD=kLp9nReY4vXqA7mZ8wB3QcG6FsE1oNtH5jUiD2fK0zRyS9CxT8V1Mq==
 TRACKER_ADMIN_TOKEN=nP6rL2gKbY8xW5zA9mQ4jE3vC7sR1tH0oB9fN6dK5uI8eT2yV1nX4q==
 GF_SECURITY_ADMIN_PASSWORD=wQ9tR4nM7bX2zA8kY6pL5sG1oE3vN0cF9eT8jU4dK7hB6rW5iQ2nM==
 
+# === DOMAIN CONFIGURATION ===
+DOMAIN_NAME=your-domain.com                    # Your actual domain
+CERTBOT_EMAIL=admin@your-domain.com            # Your email for Let's Encrypt
+
 # === BACKUP CONFIGURATION ===
 ENABLE_DB_BACKUPS=true
 BACKUP_RETENTION_DAYS=7
@@ -396,12 +412,12 @@ BACKUP_RETENTION_DAYS=7
 **⚠️ Security Note**: The `production.env` file contains sensitive secrets and is git-ignored.
 Never commit this file to version control.
 
-#### Step 3: Validate Configuration
+#### Step 4: Validate Configuration
 
 Validate your production configuration before deployment:
 
 ```bash
-# Validate configuration
+# Validate configuration (will work only after secrets are configured)
 make infra-config-production
 
 # Expected output:

docs/issues/21-complete-application-installation-automation.md

@@ -83,19 +83,19 @@ well-guided.
 
 **Last Updated**: 2025-07-29
 
-| Component                     | Status             | Description                                        | Notes                                             |
-| ----------------------------- | ------------------ | -------------------------------------------------- | ------------------------------------------------- |
-| **Infrastructure Foundation** | ✅ **Complete**    | VM provisioning, cloud-init, basic system setup    | Fully automated via provision-infrastructure.sh   |
-| **Application Foundation**    | ✅ **Complete**    | Docker deployment, basic app orchestration         | Fully automated via deploy-app.sh                 |
-| **Environment Templates**     | ✅ **Complete**    | SSL/domain/backup variables added to templates     | Templates updated with all required variables     |
-| **Secret Generation Helper**  | ✅ **Complete**    | Helper script for generating secure secrets        | generate-secrets.sh implemented                   |
-| **Basic Nginx Templates**     | ✅ **Complete**    | HTTP nginx configuration template exists           | nginx.conf.tpl with HTTP + commented HTTPS        |
-| **configure-env.sh Updates**  | ✅ **Complete**    | SSL/backup variable validation implemented          | Comprehensive validation with email/boolean checks |
-| **SSL Certificate Scripts**   | ❌ **Not Started** | Create SSL generation and configuration scripts    | Core SSL automation needed                        |
-| **HTTPS Nginx Templates**     | 🔄 **Partial**     | HTTPS configuration exists but commented out       | Current template has HTTPS but needs activation   |
-| **MySQL Backup Scripts**      | ❌ **Not Started** | Create MySQL backup automation scripts             | Referenced by cron template but doesn't exist     |
-| **deploy-app.sh Extensions**  | ❌ **Not Started** | SSL/backup automation not yet integrated           | Foundation exists, needs SSL/backup stages        |
-| **Crontab Templates**         | 🔄 **Partial**     | Templates exist but reference non-existent scripts | Templates created, scripts and integration needed |
+| Component                     | Status             | Description                                        | Notes                                              |
+| ----------------------------- | ------------------ | -------------------------------------------------- | -------------------------------------------------- |
+| **Infrastructure Foundation** | ✅ **Complete**    | VM provisioning, cloud-init, basic system setup    | Fully automated via provision-infrastructure.sh    |
+| **Application Foundation**    | ✅ **Complete**    | Docker deployment, basic app orchestration         | Fully automated via deploy-app.sh                  |
+| **Environment Templates**     | ✅ **Complete**    | SSL/domain/backup variables added to templates     | Templates updated with all required variables      |
+| **Secret Generation Helper**  | ✅ **Complete**    | Helper script for generating secure secrets        | generate-secrets.sh implemented                    |
+| **Basic Nginx Templates**     | ✅ **Complete**    | HTTP nginx configuration template exists           | nginx.conf.tpl with HTTP + commented HTTPS         |
+| **configure-env.sh Updates**  | ✅ **Complete**    | SSL/backup variable validation implemented         | Comprehensive validation with email/boolean checks |
+| **SSL Certificate Scripts**   | ❌ **Not Started** | Create SSL generation and configuration scripts    | Core SSL automation needed                         |
+| **HTTPS Nginx Templates**     | 🔄 **Partial**     | HTTPS configuration exists but commented out       | Current template has HTTPS but needs activation    |
+| **MySQL Backup Scripts**      | ❌ **Not Started** | Create MySQL backup automation scripts             | Referenced by cron template but doesn't exist      |
+| **deploy-app.sh Extensions**  | ❌ **Not Started** | SSL/backup automation not yet integrated           | Foundation exists, needs SSL/backup stages         |
+| **Crontab Templates**         | 🔄 **Partial**     | Templates exist but reference non-existent scripts | Templates created, scripts and integration needed  |
 | **Documentation Updates**     | 🔄 **Partial**     | ADR-004 updated for deployment automation config   | Deployment guides need updates post-implementation |
 
 **Current Progress**: 50% complete (6/12 components fully implemented)

infrastructure/.gitignore

@@ -10,10 +10,11 @@
 terraform.tfplan
 terraform.tfplan.*
 
-# Environment files with secrets (keep templates)
+# Environment files with secrets (keep templates and defaults)
 config/environments/production.env
 config/environments/*.env
 !config/environments/*.env.tpl
+!config/environments/*.defaults
 
 # Cloud-init generated files
 user-data.yaml

infrastructure/config/environments/README.md

@@ -1,12 +1,30 @@
-# Environment Configuration Templates
+# Environment Configuration
 
-This directory contains environment-specific configuration templates that are processed
-during deployment to generate the final configuration files.
+This directory contains the environment configuration system for the Torrust Tracker Demo.
 
-## Files
+## Files Overview
 
-- `local.env.tpl` - Local development environment template
-- `production.env.tpl` - Production environment template (requires manual setup)
+### Templates and Configuration
+
+- **`base.env.tpl`** - Single base template for all environments (uses variable substitution)
+- **`local.defaults`** - Default values for local development environment
+- **`production.defaults`** - Default values for production environment template
+
+### Generated Files (Git-Ignored)
+
+- **`local.env`** - Generated local environment configuration (regenerated automatically)
+- **`production.env`** - Generated production environment configuration (manual secrets required)
+
+## How It Works
+
+### Twelve-Factor Compliance
+
+This system follows twelve-factor app principles by:
+
+1. **Single Source of Truth**: One base template (`base.env.tpl`) for all environments
+2. **Environment-Specific Configuration**: Default files define environment-specific values
+3. **Separation of Concerns**: Configuration (defaults) separated from code (scripts)
+4. **Version Control**: Default files are tracked, generated files with secrets are ignored
 
 ## Template Processing
 
@@ -194,6 +212,50 @@ but this is actually a good practice that ensures:
    ssh torrust@$VM_IP 'cd torrust-tracker-demo && cat application/.env'
    ```
 
+## Default Files System (New Approach)
+
+### Configuration Architecture
+
+The environment configuration system now uses a single base template with external default files:
+
+- **`base.env.tpl`**: Single template with variable placeholders (`${VARIABLE_NAME}`)
+- **`local.defaults`**: Default values for local development
+- **`production.defaults`**: Default placeholder values for production
+
+### Benefits
+
+1. **DRY Principle**: Single source of truth for all environment variables
+2. **Maintainability**: Add variables once in base template, define values in defaults
+3. **Version Control**: Default values are tracked and can be customized
+4. **Consistency**: Same template processing logic for all environments
+
+### Usage
+
+```bash
+# Generate local environment (uses local.defaults)
+./infrastructure/scripts/configure-env.sh local
+
+# Generate production template (uses production.defaults)
+./infrastructure/scripts/configure-env.sh production
+
+# Generate secure production secrets
+./infrastructure/scripts/configure-env.sh generate-secrets
+```
+
+### Customizing Defaults
+
+Edit the `.defaults` files to change environment-specific values:
+
+```bash
+# Change local development domain
+vim infrastructure/config/environments/local.defaults
+
+# Change production backup retention
+vim infrastructure/config/environments/production.defaults
+```
+
+The next time you run configuration generation, your changes will be applied.
+
 ## Security Notes
 
 - **Never commit production secrets** - Use placeholder values in templates

infrastructure/config/environments/base.env.tpl

@@ -0,0 +1,47 @@
+# ${ENVIRONMENT_DESCRIPTION}
+# ${ENVIRONMENT_INSTRUCTIONS}
+
+ENVIRONMENT=${ENVIRONMENT}
+GENERATION_DATE=$(date '+%Y-%m-%d %H:%M:%S')
+
+${TEMPLATE_PROCESSING_VARS}
+
+# === SECRETS (DOCKER SERVICES) ===
+${SECRETS_DESCRIPTION}
+
+# Database Secrets
+MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
+MYSQL_DATABASE=torrust_tracker
+MYSQL_USER=torrust
+MYSQL_PASSWORD=${MYSQL_PASSWORD}
+
+# Tracker API Token${TRACKER_TOKEN_DESCRIPTION}
+TRACKER_ADMIN_TOKEN=${TRACKER_ADMIN_TOKEN}
+
+# Grafana Admin Credentials
+GF_SECURITY_ADMIN_USER=admin
+GF_SECURITY_ADMIN_PASSWORD=${GF_SECURITY_ADMIN_PASSWORD}
+
+# === SSL CERTIFICATE CONFIGURATION ===
+# Domain name for SSL certificates${DOMAIN_NAME_DESCRIPTION}
+DOMAIN_NAME=${DOMAIN_NAME}
+# Email for ${CERTBOT_EMAIL_DESCRIPTION}
+CERTBOT_EMAIL=${CERTBOT_EMAIL}
+# Enable SSL certificates${ENABLE_SSL_DESCRIPTION}
+ENABLE_SSL=${ENABLE_SSL}
+
+# === BACKUP CONFIGURATION ===
+# Enable daily database backups${BACKUP_DESCRIPTION}
+ENABLE_DB_BACKUPS=${ENABLE_DB_BACKUPS}
+# Backup retention period in days
+BACKUP_RETENTION_DAYS=${BACKUP_RETENTION_DAYS}
+
+# === DEPLOYMENT AUTOMATION CONFIGURATION ===
+# These variables control deployment scripts and automation, not service configuration.
+# They are consumed by infrastructure scripts (deploy-app.sh, SSL generation, backup automation)
+# rather than individual Docker services. This follows 12-factor principles for deployment automation.
+
+# === DOCKER CONFIGURATION ===
+
+# User ID for file permissions${USER_ID_DESCRIPTION}
+USER_ID=${USER_ID}

infrastructure/config/environments/local.defaults

@@ -0,0 +1,27 @@
+# Local Development Environment Default Values
+# These values are used to generate local.env from the base template
+# Safe default values for local development and testing
+
+ENVIRONMENT_DESCRIPTION="Local Development Environment Configuration"
+ENVIRONMENT_INSTRUCTIONS="Generated from base template for local development and testing"
+ENVIRONMENT="local"
+TEMPLATE_PROCESSING_VARS="
+# Template processing variables
+DOLLAR=\$"
+SECRETS_DESCRIPTION=""
+MYSQL_ROOT_PASSWORD="root_secret_local"
+MYSQL_PASSWORD="tracker_secret_local"
+TRACKER_TOKEN_DESCRIPTION=""
+TRACKER_ADMIN_TOKEN="MyAccessToken"
+GF_SECURITY_ADMIN_PASSWORD="admin_secret_local"
+DOMAIN_NAME_DESCRIPTION=" (local testing with fake domains)"
+DOMAIN_NAME="test.local"
+CERTBOT_EMAIL_DESCRIPTION="certificate registration (test email for local)"
+CERTBOT_EMAIL="test@test.local"
+ENABLE_SSL_DESCRIPTION=" (false for local testing)"
+ENABLE_SSL="false"
+BACKUP_DESCRIPTION=" (disabled for local testing)"
+ENABLE_DB_BACKUPS="false"
+BACKUP_RETENTION_DAYS="3"
+USER_ID_DESCRIPTION=""
+USER_ID="1000"

infrastructure/config/environments/local.env.tpl

@@ -0,0 +1,26 @@
+# Production Environment Default Values  
+# These values are used to generate production.env template from the base template
+# Contains placeholder values that must be replaced with secure secrets
+
+ENVIRONMENT_DESCRIPTION="Production Environment Configuration Template"
+ENVIRONMENT_INSTRUCTIONS="Copy this file to production.env and replace placeholder values with secure secrets"
+ENVIRONMENT="production"
+TEMPLATE_PROCESSING_VARS=""
+SECRETS_DESCRIPTION="
+# IMPORTANT: Replace ALL placeholder values with actual secure secrets before deployment!"
+MYSQL_ROOT_PASSWORD="REPLACE_WITH_SECURE_ROOT_PASSWORD"
+MYSQL_PASSWORD="REPLACE_WITH_SECURE_PASSWORD"
+TRACKER_TOKEN_DESCRIPTION=" (Used for administrative API access)"
+TRACKER_ADMIN_TOKEN="REPLACE_WITH_SECURE_ADMIN_TOKEN"
+GF_SECURITY_ADMIN_PASSWORD="REPLACE_WITH_SECURE_GRAFANA_PASSWORD"
+DOMAIN_NAME_DESCRIPTION=" (required for production)"
+DOMAIN_NAME="REPLACE_WITH_YOUR_DOMAIN"
+CERTBOT_EMAIL_DESCRIPTION="Let's Encrypt certificate registration (required for production)"
+CERTBOT_EMAIL="REPLACE_WITH_YOUR_EMAIL"
+ENABLE_SSL_DESCRIPTION=" (true for production, false for testing)"
+ENABLE_SSL="true"
+BACKUP_DESCRIPTION=" (true/false)"
+ENABLE_DB_BACKUPS="true"
+BACKUP_RETENTION_DAYS="7"
+USER_ID_DESCRIPTION=" (match host user)"
+USER_ID="1000"