Phase 2: 12-Factor App Refactoring

[josecelano]

Overview

This issue implements Phase 2 of the Hetzner migration plan: refactoring the repository to follow 12-Factor App methodology where applicable.

Parent Issue: #3 (Hetzner Migration Plan)

Objective

Refactor repository to follow 12-Factor App methodology for better deployment practices and environment consistency, while respecting the Torrust Tracker's architectural constraints.

Reference Documentation

See detailed plan in infrastructure/docs/refactoring/twelve-factor-refactor/

Key Changes

• Configuration via environment: Move all config to environment variables
• Dependency isolation: Explicit dependency declaration in Docker
• Single-instance processes: Ensure tracker processes are properly isolated (Note: Torrust Tracker cannot be horizontally scaled due to in-memory peer data)
• Port binding: Clean service port configuration
• Logs as streams: Structured logging to stdout/stderr
• Environment parity: Dev/staging/prod environment consistency

Tasks

• Implement configuration refactoring (see phase-1-implementation.md)
• Update Docker configurations
• Refactor environment variable management
• Update deployment scripts
• Update documentation

Deliverable

12-Factor compliant repository structure (within architectural constraints)

Acceptance Criteria

• All configuration is managed via environment variables
• Docker configurations follow 12-Factor principles
• Processes are properly isolated (single-instance deployment)
• Port binding is clean and configurable
• Logs are streamed to stdout/stderr
• Development, staging, and production environments are consistent
• Documentation is updated to reflect new structure

Architectural Note

Important: The Torrust Tracker cannot be horizontally scaled because:

1. It stores critical peer list data in memory (not in database)
2. Only secondary data (metrics, whitelist, user keys) is stored in the database
3. SQLite usage (when configured) creates file-based storage that cannot be easily shared between instances

This refactoring focuses on other 12-Factor principles while maintaining single-instance deployment.

Dependencies

• Depends on Phase 1 (Database Migration to MySQL)