docs: add redesign documentation for configuration management

- Add configuration variables and user inputs analysis
- Add environment naming and configuration design
- Update redesign README with new documentation structure
- Update project words dictionary with new terms

These documents support the configuration management implementation
design for the project redesign from PoC to production.

Author: josecelano

docs/redesign/README.md

@@ -80,9 +80,9 @@ After a quick review we move to Phase 2 (measure current behaviour: performance,
 
 **Implementation Phases** (in new `torrust-tracker-installer` repository):
 
-5. Implementation (build the new system)
-6. Testing & validation (comprehensive testing)
-7. Migration & deployment (production rollout)
+1. Implementation (build the new system)
+2. Testing & validation (comprehensive testing)
+3. Migration & deployment (production rollout)
 
 ## Next Up (Short List)
 

docs/redesign/phase1-requirements/configuration-variables-and-user-inputs.md

@@ -0,0 +1,366 @@
+# Configuration Variables and User Inputs
+
+## Overview
+
+This document defines the comprehensive set of configuration variables and user inputs
+required for successful deployment of Torrust Tracker environments, based on the actual
+Proof of Concept (PoC) implementation. It categorizes variables by their purpose,
+provides real examples from the PoC codebase, and establishes the two-tier configuration
+architecture used in production.
+
+## Configuration Architecture
+
+### Two-Tier System
+
+The PoC implements a **two-tier configuration architecture**:
+
+1. **Environment-Specific Configuration** (`infrastructure/config/environments/`):
+
+   - `staging-hetzner-staging.env` - Staging environment for Hetzner Cloud
+   - `development-libvirt.env` - Development environment for local libvirt
+   - `e2e-libvirt.env` - End-to-end testing environment
+
+2. **Provider-Specific Configuration** (`infrastructure/config/providers/`):
+   - `hetzner-staging.env` - Hetzner Cloud provider defaults and authentication
+   - `libvirt.env` - libvirt provider defaults and local virtualization settings
+
+### Key Architectural Notes
+
+> **Important**: All environments have a **common parts** and another part that **depends on the provider**.
+> We have not decided the format yet (multiformat would be ideal). The configuration system must handle:
+>
+> - Arrays (e.g., lists of UDP/HTTP tracker ports)
+> - Common vs provider-specific parts
+> - Multiple configuration strategy options with schema validation
+
+## Configuration Variable Classification Tree
+
+```text
+Configuration Variables
+├── 1. General Configuration
+│   ├── Domain Configuration (TRACKER_DOMAIN, GRAFANA_DOMAIN, CERTBOT_EMAIL)
+│   ├── Environment Identification (ENVIRONMENT_TYPE, PROVIDER)
+│   └── Floating IP Configuration (FLOATING_IPV4, FLOATING_IPV6)
+├── 2. Provisioning Configuration
+│   ├── VM Configuration (VM_NAME, VM_MEMORY, VM_VCPUS, VM_DISK_SIZE)
+│   ├── Provider Settings (HETZNER_*, PROVIDER_LIBVIRT_*)
+│   ├── Authentication (SSH_PUBLIC_KEY, HETZNER_API_TOKEN)
+│   └── Firewall Configuration (implicit via tracker ports)
+└── 3. Deployment Configuration
+    ├── Docker Compose Services
+    │   ├── MySQL (MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD, MYSQL_DATABASE, MYSQL_USER)
+    │   ├── Tracker (TRACKER_ADMIN_TOKEN + port configuration)
+    │   ├── Grafana (GF_SECURITY_ADMIN_USER, GF_SECURITY_ADMIN_PASSWORD)
+    │   └── System (USER_ID, DOLLAR)
+    ├── Backup Configuration (ENABLE_DB_BACKUPS, BACKUP_RETENTION_DAYS)
+    ├── SSL Certificate Management (ENABLE_SSL, SSL certificate paths)
+    └── Deployment Automation (infrastructure scripts configuration)
+```
+
+## Tracker Port Configuration
+
+### UDP Tracker Ports
+
+The PoC configures **two UDP tracker endpoints**:
+
+```toml
+# From tracker.toml.tpl configuration
+[[udp_trackers]]
+bind_address = "0.0.0.0:6868"  # Internal testing and alternative endpoint
+
+[[udp_trackers]]
+bind_address = "0.0.0.0:6969"  # Official public tracker endpoint
+```
+
+**Port 6868**: Internal testing UDP tracker
+
+- **Purpose**: Development testing and alternative endpoint when 6969 is under heavy load
+- **Security**: Public access allowed but not advertised on public tracker lists
+- **Usage**: Backup endpoint for tracker protocol testing
+
+**Port 6969**: Official public UDP tracker
+
+- **Purpose**: Primary BitTorrent UDP tracker endpoint for production traffic
+- **Security**: Public access required for torrent client connections
+- **Usage**: Heavy production load, primary endpoint for announce/scrape operations
+
+### HTTP Tracker Ports
+
+The PoC configures **one HTTP tracker endpoint**:
+
+```toml
+# From tracker.toml.tpl configuration
+[[http_trackers]]
+bind_address = "0.0.0.0:7070"  # Internal HTTP tracker via Nginx proxy
+```
+
+**Port 7070**: HTTP tracker (internal, accessed via Nginx proxy)
+
+- **Purpose**: HTTP tracker protocol support accessed through HTTPS reverse proxy
+- **Security**: Internal port, public access via port 443 (HTTPS) through Nginx
+- **Usage**: HTTP announce/scrape operations with SSL termination
+
+### API and Monitoring Ports
+
+```toml
+# From tracker.toml.tpl configuration
+[http_api]
+bind_address = "0.0.0.0:1212"  # API and metrics endpoint
+
+[health_check_api]
+bind_address = "127.0.0.1:1313"  # Health check (localhost only)
+```
+
+**Port 1212**: Tracker API and Metrics
+
+- **Purpose**: REST API for tracker management and Prometheus metrics collection
+- **Security**: Internal port, public access via port 443 (HTTPS) through Nginx proxy
+- **Usage**: Statistics, health checks, Prometheus scraping
+
+**Port 1313**: Health Check API
+
+- **Purpose**: Internal health check endpoint for system monitoring
+- **Security**: Localhost only (127.0.0.1), not accessible externally
+- **Usage**: Container health checks and internal monitoring
+
+## Real Configuration Examples from PoC
+
+### 1. General Configuration Variables
+
+#### Environment Identification
+
+```bash
+# staging-hetzner-staging.env
+ENVIRONMENT_TYPE=staging
+PROVIDER=hetzner-staging
+
+# development-libvirt.env
+ENVIRONMENT_TYPE=development
+PROVIDER=libvirt
+
+# e2e-libvirt.env
+ENVIRONMENT_TYPE=e2e
+PROVIDER=libvirt
+```
+
+**ENVIRONMENT_TYPE**: Identifies the deployment environment (staging, production, development, e2e)
+**PROVIDER**: Specifies the infrastructure provider (hetzner-staging, libvirt)
+
+#### Domain Configuration
+
+```bash
+# staging-hetzner-staging.env
+TRACKER_DOMAIN=tracker.staging-torrust-demo.com
+GRAFANA_DOMAIN=grafana.staging-torrust-demo.com
+[email protected]
+
+# development-libvirt.env
+TRACKER_DOMAIN=tracker.test.local
+GRAFANA_DOMAIN=grafana.test.local
+
+# e2e-libvirt.env
+TRACKER_DOMAIN=tracker.e2e.test.local
+GRAFANA_DOMAIN=grafana.e2e.test.local
+```
+
+**TRACKER_DOMAIN**: Primary domain for tracker service and API endpoints
+**GRAFANA_DOMAIN**: Dedicated subdomain for Grafana monitoring dashboard
+**CERTBOT_EMAIL**: Email for Let's Encrypt certificate registration (production only)
+
+#### Floating IP Configuration
+
+```bash
+# staging-hetzner-staging.env
+FLOATING_IPV4=78.47.140.132
+FLOATING_IPV6=2a01:4f8:1c17:a01d::1
+```
+
+**FLOATING_IPV4**: Hetzner floating IPv4 address for stable DNS mapping
+**FLOATING_IPV6**: Hetzner floating IPv6 address for dual-stack networking
+
+### 2. Provisioning Configuration Variables
+
+#### VM Configuration
+
+```bash
+# staging-hetzner-staging.env
+VM_NAME=staging-tracker
+VM_MEMORY=4096
+VM_VCPUS=4
+VM_DISK_SIZE=50
+
+# development-libvirt.env
+VM_NAME=development-tracker
+VM_MEMORY=2048
+VM_VCPUS=2
+VM_DISK_SIZE=30
+
+# e2e-libvirt.env
+VM_NAME=e2e-tracker
+VM_MEMORY=2048
+VM_VCPUS=2
+VM_DISK_SIZE=20
+```
+
+**VM_NAME**: Identifier for the virtual machine instance
+**VM_MEMORY**: RAM allocation in MB (staging: 4GB, dev/testing: 2GB)
+**VM_VCPUS**: Virtual CPU cores (staging: 4, dev/testing: 2)
+**VM_DISK_SIZE**: Disk space in GB (staging: 50GB, development: 30GB, e2e: 20GB)
+
+#### Provider-Specific Settings
+
+```bash
+# hetzner-staging.env
+HETZNER_SERVER_TYPE=cpx31
+HETZNER_LOCATION=fsn1
+HETZNER_IMAGE=ubuntu-24.04
+VM_MEMORY_DEFAULT=8192
+
+# libvirt.env
+PROVIDER_LIBVIRT_URI=qemu:///system
+PROVIDER_LIBVIRT_POOL=user-default
+PROVIDER_LIBVIRT_BASE_IMAGE_URL=https://cloud-images.ubuntu.com/releases/24.04/release/ubuntu-24.04-server-cloudimg-amd64.img
+VM_MEMORY_DEFAULT=2048
+```
+
+**HETZNER_SERVER_TYPE**: Hetzner Cloud server type (cpx31 = 4 vCPU, 8GB RAM, 160GB SSD)
+**HETZNER_LOCATION**: Hetzner datacenter location (fsn1 = Falkenstein, Germany)
+**PROVIDER_LIBVIRT_URI**: libvirt connection URI for local virtualization
+**PROVIDER_LIBVIRT_POOL**: Storage pool for VM disks and images
+
+#### Authentication Configuration
+
+```bash
+# hetzner-staging.env
+HETZNER_API_TOKEN=your-hetzner-cloud-api-token-here
+HETZNER_DNS_API_TOKEN=your-hetzner-dns-api-token-here
+
+# All environments
+SSH_PUBLIC_KEY=ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC...
+```
+
+**HETZNER_API_TOKEN**: API token for Hetzner Cloud infrastructure management
+**HETZNER_DNS_API_TOKEN**: API token for Hetzner DNS service management
+**SSH_PUBLIC_KEY**: Public SSH key for VM access authentication
+
+### 3. Deployment Configuration Variables
+
+#### Docker Compose Service Configuration
+
+```bash
+# All environments
+USER_ID=1000
+DOLLAR=$
+
+# MySQL Database Configuration
+MYSQL_ROOT_PASSWORD=secure_root_password_here
+MYSQL_PASSWORD=secure_user_password_here
+MYSQL_DATABASE=torrust_tracker
+MYSQL_USER=torrust
+
+# Tracker Service Configuration
+TRACKER_ADMIN_TOKEN=secure_admin_token_here
+
+# Grafana Configuration
+GF_SECURITY_ADMIN_USER=admin
+GF_SECURITY_ADMIN_PASSWORD=secure_grafana_password_here
+```
+
+**USER_ID**: Unix user ID for container processes (1000 = torrust user)
+**DOLLAR**: Literal dollar sign for template processing (preserves nginx variables)
+**MYSQL_ROOT_PASSWORD**: MySQL root user password for database administration
+**MYSQL_PASSWORD**: MySQL application user password for tracker database access
+**TRACKER_ADMIN_TOKEN**: Authentication token for tracker REST API access
+**GF_SECURITY_ADMIN_PASSWORD**: Grafana admin user password for dashboard access
+
+#### Backup Configuration
+
+```bash
+# staging-hetzner-staging.env
+ENABLE_DB_BACKUPS=true
+BACKUP_RETENTION_DAYS=30
+
+# development-libvirt.env
+ENABLE_DB_BACKUPS=true
+BACKUP_RETENTION_DAYS=3
+
+# e2e-libvirt.env
+ENABLE_DB_BACKUPS=false
+```
+
+**ENABLE_DB_BACKUPS**: Enable automated MySQL database backup system
+**BACKUP_RETENTION_DAYS**: Number of days to retain backup files (staging: 30, dev: 3, e2e: disabled)
+
+#### SSL Certificate Management
+
+```bash
+# staging-hetzner-staging.env
+ENABLE_SSL=true
+SSL_GENERATION_METHOD=letsencrypt
+
+# development-libvirt.env
+ENABLE_SSL=true
+SSL_GENERATION_METHOD=self-signed
+
+# e2e-libvirt.env
+ENABLE_SSL=false
+```
+
+**ENABLE_SSL**: Enable HTTPS with SSL certificate generation
+**SSL_GENERATION_METHOD**: Certificate source (letsencrypt for production, self-signed for development)
+
+## Multi-Format Configuration Strategy
+
+### Current Architecture Benefits
+
+The two-tier system provides:
+
+- **Scalability**: Easy addition of new providers without environment duplication
+- **Maintainability**: Common provider settings shared across environments
+- **Security**: Provider authentication separated from environment configuration
+- **Flexibility**: Environment-specific overrides of provider defaults
+
+### Future Multi-Format Considerations
+
+> **Note**: The configuration format decision is pending. A multiformat approach would ideally support:
+
+1. **Array Configuration**: Lists of tracker ports, SSL domains, backup targets
+2. **Schema Validation**: Multiple validation strategies for different complexity levels
+3. **Common vs Provider-Specific Parts**: Clear separation with inheritance patterns
+4. **Configuration Templates**: Reusable patterns for common deployment scenarios
+
+### Example Array Configuration
+
+```yaml
+# Future multiformat example
+tracker_ports:
+  udp:
+    - port: 6868
+      purpose: "internal testing"
+      public: false
+    - port: 6969
+      purpose: "production traffic"
+      public: true
+  http:
+    - port: 7070
+      purpose: "http tracker via nginx"
+      proxy: true
+```
+
+This multiformat strategy would enable more sophisticated configuration validation and better
+support for complex deployment scenarios while maintaining the proven two-tier architecture.
+
+## Implementation Design
+
+The implementation of configuration management is documented in the design specifications:
+
+- **[Configuration Management Implementation]**
+  (../phase3-design/configuration-management-implementation.md) -
+  Comprehensive technical design including architecture, file formats, schema validation,
+  and processing pipeline
+- **[Environment Naming and Configuration]**
+  (../phase3-design/environment-naming-and-configuration.md) -
+  Environment naming conventions and configuration inheritance design
+
+These design documents provide detailed technical specifications for implementing the
+configuration requirements outlined in this document.