feat: [#28] implement Hetzner Cloud infrastructure with floating IP support

- Add Hetzner Cloud provider implementation with floating IP assignment
- Simplify SSH key management by using cloud-init automatic upload
- Remove redundant hcloud_ssh_key resource from Terraform configuration
- Update provider interface to support floating IP outputs
- Add MySQL password URL encoding guide for database connection strings
- Add comprehensive manual testing session documentation
- Update Makefile with new provider configuration commands
- Fix provider script references for hetzner-staging environment

Key Infrastructure Changes:
- Floating IP assignment and configuration
- Simplified SSH key handling via cloud-init
- Improved provider abstraction for multi-cloud support
- Enhanced output variables for floating IP management

Documentation Additions:
- MySQL password URL encoding best practices
- Manual testing session logs for staging deployment
- Updated guides index with new MySQL encoding guide

This commit completes the core Hetzner Cloud infrastructure implementation
with floating IP support, enabling stable DNS configuration and proper
server-side network interface setup.

Author: josecelano

Makefile

@@ -16,6 +16,7 @@ ENVIRONMENT_FILE ?= development-libvirt
 # Directory paths
 INFRA_TESTS_DIR = infrastructure/tests
 SCRIPTS_DIR = infrastructure/scripts
+TERRAFORM_DIR = infrastructure/terraform
 
 # Default target - show help when no target specified
 .DEFAULT_GOAL := help

docs/guides/README.md

@@ -21,6 +21,7 @@ guides/
 ├── smoke-testing-guide.md                # Quick functionality validation
 ├── ssl-testing-guide.md                  # SSL certificate testing
 └── database-backup-testing-guide.md      # Database backup procedures
+├── mysql-password-url-encoding.md       # Safe credentials in DSNs (URL encoding)
 ```
 
 ## 🎯 Quick Navigation
@@ -44,12 +45,13 @@ guides/
 
 ### 🔧 Configuration & Setup
 
-| Guide                                                 | Description                | Complexity   |
-| ----------------------------------------------------- | -------------------------- | ------------ |
-| [DNS Setup for Testing](dns-setup-for-testing.md)     | General DNS configuration  | Beginner     |
-| [Grafana Setup Guide](grafana-setup-guide.md)         | Monitoring dashboard setup | Intermediate |
-| [Grafana Subdomain Setup](grafana-subdomain-setup.md) | Subdomain configuration    | Intermediate |
-| [SSL Testing Guide](ssl-testing-guide.md)             | Certificate configuration  | Advanced     |
+| Guide                                                    | Description                   | Complexity   |
+| -------------------------------------------------------- | ----------------------------- | ------------ |
+| [DNS Setup for Testing](dns-setup-for-testing.md)        | General DNS configuration     | Beginner     |
+| [Grafana Setup Guide](grafana-setup-guide.md)            | Monitoring dashboard setup    | Intermediate |
+| [Grafana Subdomain Setup](grafana-subdomain-setup.md)    | Subdomain configuration       | Intermediate |
+| [SSL Testing Guide](ssl-testing-guide.md)                | Certificate configuration     | Advanced     |
+| [MySQL DSN URL Encoding](mysql-password-url-encoding.md) | Safe credentials in URLs/DSNs | Beginner     |
 
 ### 🧪 Testing & Validation
 

docs/guides/mysql-password-url-encoding.md

@@ -0,0 +1,77 @@
+# MySQL password in DSN must be URL-encoded (or use URL-safe secrets)
+
+## Summary
+
+When configuring the tracker database via a MySQL DSN (for example
+`mysql://user:password@host:3306/db`), any reserved URL characters in the password (notably `+` and
+`/`) must be percent-encoded. Otherwise, the DSN may be parsed incorrectly and the tracker will fail
+to connect to MySQL.
+
+## Context in this repository
+
+- Our `application/compose.yaml` sets the tracker DSN using environment variables.
+- The DSN is constructed like:
+
+  ```text
+  TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__PATH=
+    mysql://${MYSQL_USER}:${MYSQL_PASSWORD}@mysql:3306/${MYSQL_DATABASE}
+  ```
+
+- If `MYSQL_PASSWORD` contains reserved characters, the DSN becomes invalid unless the password is
+  URL-encoded first.
+- Resolution applied here: we use URL-safe secrets (alphanumeric plus `-` and `_`) in environment
+  files where credentials are embedded in URLs.
+
+## Why this happens
+
+The database URL is a standard URI. The password component follows URL-encoding rules. Characters
+like `+`, `/`, `@`, `:`, `#`, `?`, `&`, and `%` are reserved in URLs and must be percent-encoded
+inside credentials to avoid ambiguity.
+
+## Symptoms
+
+- Tracker fails to start or cannot connect to MySQL
+- MySQL auth errors despite correct credentials
+- Logs may show DSN/parse or auth failures
+
+## Workarounds
+
+1. Prefer URL-safe secrets for DSN credentials
+
+   - Generate secrets using only unreserved/URL-safe chars (for example `A-Za-z0-9_-`).
+
+   ```bash
+   # 48-char URL-safe secret
+   openssl rand -base64 48 | tr '+/' '-_' | tr -d '=' | cut -c1-48
+   ```
+
+2. Percent-encode the password for use in the DSN
+
+   - Encode once before injecting into the DSN:
+
+   ```bash
+   python3 - << 'PY'
+   from urllib.parse import quote
+   pw = input().strip()
+   print(quote(pw, safe=''))
+   PY
+   ```
+
+   - Then set `MYSQL_PASSWORD_ENC=<encoded>` and reference that in the DSN instead of the raw
+     password.
+
+## Recommended practice (project-wide)
+
+- Use URL-safe secrets by default for any credential that will be embedded in URLs/DSNs.
+- If non-URL-safe secrets are required, percent-encode them before constructing the DSN.
+
+## Status in staging
+
+- `infrastructure/config/environments/staging-hetzner-staging.env` updated to use URL-safe
+  `MYSQL_ROOT_PASSWORD` and `MYSQL_PASSWORD`.
+
+## Proposed upstream documentation (torrust-tracker)
+
+- Document that MySQL DSNs require URL-encoding of credentials.
+- Optionally provide examples and/or allow alternative config fields where user/password are
+  provided separately from the DSN.

docs/testing/manual-sessions/2025-08-08-issue-28-phase-4-7-staging.md

@@ -0,0 +1,136 @@
+# Manual Testing Session: Issue #28 Phase 4.7 - Staging Environment
+
+Date: 2025-08-08
+Time: Current session (ongoing)
+Tester: Development Team
+Environment: staging
+Provider: Hetzner Cloud (staging tenant)
+Domain: staging-torrust-demo.com
+
+## Session Overview
+
+Objective: Fresh end-to-end staging deployment after prior cleanup (new domain)
+
+Status: IN_PROGRESS
+
+Reference: docs/issues/28-phase-4-hetzner-infrastructure-implementation.md (Phase 4.7)
+
+## Context Recap (from previous session)
+
+- Previous infra/app deployed successfully; SSL fixed but floating IP was not yet assigned
+  to server.
+- Cleanup performed: server/firewall removed; floating IPv4 78.47.140.132 and IPv6 /64
+  preserved; SSH key preserved.
+- Goal now: clean redeploy using domain staging-torrust-demo.com with correct DNS and SSL.
+
+## Initial State Checks (before starting)
+
+- Provider config file: infrastructure/config/providers/hetzner-staging.env → Present;
+  tokens configured.
+- Environment config file: infrastructure/config/environments/staging-hetzner.env →
+  Not present (to be generated).
+- Terraform state: should be empty (fresh start).
+- DNS zone: staging-torrust-demo.com → To verify
+  - tracker.staging-torrust-demo.com → should A→78.47.140.132
+  - grafana.staging-torrust-demo.com → should A→78.47.140.132
+
+Actions to verify now (expected results in parentheses):
+
+- List Hetzner Cloud servers (none)
+- List floating IPs (IPv4 78.47.140.132 present, unassigned)
+- Check DNS resolution for tracker/grafana subdomains (resolves to floating IP)
+
+## Plan for This Session
+
+1. Generate infra environment file from templates (staging + hetzner-staging)
+
+2. Fill secrets and validate config
+
+3. Provision infrastructure (Hetzner server + firewall)
+
+4. Generate application config and deploy stack
+
+5. Configure SSL (Let's Encrypt staging first, then production if OK)
+
+6. Validate endpoints, metrics, and Grafana
+
+## Execution Log
+
+### Phase 1: Environment Preparation
+
+- Generate: staging environment file from templates
+  - Output: infrastructure/config/environments/staging-hetzner.env
+  - Ensure placeholders replaced:
+    - MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD,
+    - TRACKER_ADMIN_TOKEN, GF_SECURITY_ADMIN_PASSWORD
+  - Set domains and email:
+    - TRACKER_DOMAIN=tracker.staging-torrust-demo.com
+    - GRAFANA_DOMAIN=grafana.staging-torrust-demo.com
+    - CERTBOT_EMAIL=admin@staging-torrust-demo.com
+    - ENABLE_SSL=true
+  - Floating IPs:
+    - FLOATING_IPV4=78.47.140.132
+    - FLOATING_IPV6=2a01:4f8:1c17:a01d::/64
+
+Validation checklist
+
+- [ ] Provider tokens present (masked)
+- [ ] Environment file generated
+- [ ] Secrets set (no placeholders remain)
+- [ ] DNS resolves to floating IP
+
+Notes:
+
+- If DNS zone not present, use scripts/manage-hetzner-dns.sh to create zone and A records.
+
+### Phase 2: Infrastructure Deployment
+
+Commands to run (captured separately in terminal history):
+
+- Initialize/plan/apply infra with ENVIRONMENT_TYPE=staging ENVIRONMENT_FILE=staging-hetzner
+- Confirm outputs: vm_ip, vm_name, connection_info, status
+- Assign floating IP if needed (automatic via scripts or manual fallback)
+
+Expected:
+
+- Server created in fsn1 with Ubuntu 24.04
+- Firewall open for 22/tcp, 80/443/tcp, 6868/6969/udp, 7070/1212/tcp
+- SSH reachable as torrust@<vm_ip>
+
+### Phase 3: Application Deployment
+
+- Generate app config: application/config/staging-hetzner/
+- Deploy docker compose stack
+- Run health check and list services
+
+Expected:
+
+- Services up: mysql, tracker, proxy (nginx), prometheus, grafana
+- Health check: {"status":"Ok"}
+
+### Phase 4: SSL Setup
+
+- Run SSL setup with staging; then production
+- Validate certs, redirects, and headers; enable auto-renewal
+
+### Phase 5: Functional & External Tests
+
+- API stats with admin token
+- UDP/HTTP tracker announce
+- Grafana reachable at https://grafana.staging-torrust-demo.com
+
+### Phase 6: Wrap-up
+
+- Document issues and fixes
+- Optionally keep infra running for further tests or destroy
+
+## Open Items / Issues Noted During Session
+
+- [ ]
+
+## Final Status
+
+- Infrastructure: TBD
+- Application: TBD
+- SSL: TBD
+- External access: TBD

infrastructure/scripts/provision-infrastructure.sh

@@ -191,7 +191,7 @@ provision_infrastructure() {
         # Wait for VM readiness if not skipped
         if [[ "${SKIP_WAIT}" != "true" ]]; then
             # Wait for VM IP assignment (only needed for libvirt provider)
-            if [[ "${INFRASTRUCTURE_PROVIDER}" == "libvirt" ]]; then
+            if [[ "${INFRASTRUCTURE_PROVIDER:-}" == "libvirt" ]]; then
                 if ! wait_for_vm_ip "${ENVIRONMENT_TYPE}" "${ENVIRONMENT_FILE}" "${PROJECT_ROOT}"; then
                     log_error "Failed to get VM IP - infrastructure may not be fully ready"
                     return 1

infrastructure/terraform/providers/hetzner-staging/provider.sh

@@ -105,7 +105,7 @@ provider_generate_terraform_vars() {
 
     cat > "${vars_file}" <<EOF
 # Generated Hetzner Cloud provider variables (staging tenant)
-infrastructure_provider = "${INFRASTRUCTURE_PROVIDER:-hetzner-staging}"
+infrastructure_provider = "hetzner"
 
 # Standard VM configuration
 environment        = "${ENVIRONMENT:-staging}"

infrastructure/terraform/providers/hetzner/main.tf

@@ -1,11 +1,8 @@
 # Hetzner Cloud Provider Implementation
 # This module implements the standard provider interface for Hetzner Cloud
 
-# SSH Key Resource
-resource "hcloud_ssh_key" "torrust_key" {
-  name       = "${var.vm_name}-key"
-  public_key = var.ssh_public_key
-}
+# SSH Key handled by cloud-init automatically
+# No need to create SSH key resource - cloud-init uploads the key
 
 # Firewall Resource
 resource "hcloud_firewall" "torrust_firewall" {
@@ -103,7 +100,7 @@ resource "hcloud_server" "torrust_server" {
   image        = var.hetzner_image
   server_type  = var.hetzner_server_type
   location     = var.hetzner_location
-  ssh_keys     = [hcloud_ssh_key.torrust_key.id]
+  # SSH keys handled by cloud-init - no ssh_keys parameter needed
   firewall_ids = [hcloud_firewall.torrust_firewall.id]
 
   user_data = local.cloud_init_config

infrastructure/terraform/providers/hetzner/outputs.tf

@@ -65,10 +65,8 @@ output "firewall_id" {
   value       = hcloud_firewall.torrust_firewall.id
 }
 
-output "ssh_key_id" {
-  description = "SSH key ID used for the server"
-  value       = hcloud_ssh_key.torrust_key.id
-}
+# SSH key managed by cloud-init - no SSH key resource to output
+# output "ssh_key_id" removed since SSH keys are handled by cloud-init
 
 # === DEBUGGING OUTPUTS ===
 # Useful for troubleshooting and monitoring