docs: organize migration plan in new plans section

josecelano · josecelano · commit 621382c95daa · 2025-07-08T09:13:10.000+01:00
- Create docs/plans/ directory for ongoing strategic plans
- Move migration plan to docs/plans/hetzner-migration-plan.md
- Add plans documentation guidelines in docs/plans/README.md
- Update docs/README.md to include plans section
- Remove timeline estimates from migration plan for flexibility
- Establish documentation structure for future strategic initiatives
diff --git a/docs/README.md b/docs/README.md
@@ -19,6 +19,13 @@ This directory currently contains cross-cutting documentation:
 - [ADR-001: Makefile Location](adr/001-makefile-location.md) - Decision to keep
   Makefile at repository root level
 
+### 📅 [`plans/`](plans/) (Ongoing Plans and Roadmaps)
+
+**Current Plans:**
+
+- [Hetzner Migration Plan](plans/hetzner-migration-plan.md) - Comprehensive plan
+  for migrating from Digital Ocean to Hetzner infrastructure
+
 ### Future Categories
 
 The following directories can be created as needed:
@@ -53,6 +60,7 @@ When adding new documentation:
 2. **Use this directory for cross-cutting concerns only**
 
    - Architecture decisions affecting multiple layers
+   - Ongoing plans and roadmaps spanning multiple phases
    - Research spanning infrastructure and application
    - Theoretical concepts and protocols
    - Performance analysis of the complete system
@@ -70,6 +78,7 @@ When adding new documentation:
 ## Documentation Guidelines
 
 - **Cross-cutting vs Specific**: Keep layer-specific docs in their respective directories
+- **Plans**: Should document strategic initiatives, migration plans, and multi-phase projects
 - **Research**: Should document findings, methodology, and conclusions
 - **ADRs**: Should follow standard ADR template format and affect multiple layers
 - **Theory**: Should explain concepts clearly with examples when possible
diff --git a/docs/plans/README.md b/docs/plans/README.md
@@ -0,0 +1,77 @@
+# Plans and Roadmaps
+
+This directory contains ongoing strategic plans, migration roadmaps, and multi-phase
+project documentation that spans across infrastructure and application concerns.
+
+## Current Plans
+
+### [Hetzner Migration Plan](hetzner-migration-plan.md)
+
+Comprehensive migration plan for moving the Torrust Tracker demo from Digital Ocean
+to Hetzner infrastructure. This plan includes:
+
+- Database migration from SQLite to MySQL
+- 12-Factor App refactoring
+- Complete deployment automation
+- Hetzner Cloud provider implementation
+- Testing and validation procedures
+- Go-live strategy
+
+**Status**: Planning phase  
+**Timeline**: 8-12 weeks estimated  
+**Scope**: Full infrastructure migration with modernization
+
+## Plan Documentation Guidelines
+
+When creating new plans:
+
+1. **Use descriptive filenames** that clearly indicate the plan scope
+2. **Include timeline estimates** with realistic expectations
+3. **Break down into phases** for complex multi-step plans
+4. **Define clear deliverables** for each phase
+5. **Include validation criteria** to measure success
+6. **Document rollback strategies** for critical changes
+7. **Cross-reference** related documentation and issues
+
+## Plan Status
+
+Plans should include a status indicator:
+
+- **Planning**: Initial planning and research phase
+- **In Progress**: Active implementation underway
+- **Testing**: Implementation complete, testing in progress
+- **Completed**: Plan successfully implemented
+- **On Hold**: Temporarily paused
+- **Cancelled**: Plan discontinued
+
+## Plan Structure
+
+Recommended structure for plan documents:
+
+```markdown
+# Plan Title
+
+## Overview
+
+Brief description and objectives
+
+## Key Decisions
+
+Major strategic decisions and rationale
+
+## Phases
+
+Detailed breakdown of implementation phases
+
+## Timeline
+
+Realistic estimates with dependencies
+
+## Success Criteria
+
+Clear metrics for measuring completion
+
+## Risk Mitigation
+
+Rollback plans and risk management
+```
diff --git a/docs/plans/hetzner-migration-plan.md b/docs/plans/hetzner-migration-plan.md
@@ -0,0 +1,245 @@
+# Torrust Tracker Demo Migration Plan - Digital Ocean to Hetzner
+
+## Overview
+
+This plan outlines the migration of the Torrust Tracker demo from Digital Ocean to Hetzner
+infrastructure. The migration prioritizes **ease of updates** over performance by maintaining
+Docker-based deployments, and follows a **complete local development and testing** approach
+before deploying to production.
+
+## Key Decisions
+
+- **Docker-first approach**: Continue using Docker for the tracker to simplify updates
+  (just pull new images)
+- **Complete local testing**: Finish all development and testing locally before creating
+  any Hetzner VMs
+- **MySQL by default**: Replace SQLite with MySQL for better production characteristics
+- **12-Factor App compliance**: Refactor the entire repository to follow modern deployment
+  practices
+
+## Migration Phases
+
+### Phase 1: Database Migration to MySQL
+
+**Objective**: Replace SQLite with MySQL as the default database
+
+#### Tasks
+
+- [ ] Add MySQL service to `docker-compose.yaml`
+- [ ] Update tracker configuration (`tracker.toml`) to use MySQL connection
+- [ ] Create MySQL initialization scripts/schema
+- [ ] Update environment variable templates (`.env.production`)
+- [ ] Update documentation for MySQL setup
+
+#### Validation
+
+- [ ] Deploy locally using `make apply`
+- [ ] Verify MySQL service starts successfully
+- [ ] Make test announce request
+- [ ] Confirm download counter increases in MySQL `torrents` table
+- [ ] Test tracker restart with persistent MySQL data
+
+**Deliverable**: Working local deployment with MySQL backend
+
+---
+
+### Phase 2: 12-Factor App Refactoring
+
+**Objective**: Refactor repository to follow [12-Factor App methodology](https://12factor.net/)
+
+**Reference**: 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
+- [ ] **Stateless processes**: Ensure tracker processes are stateless
+- [ ] **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
+
+---
+
+### Phase 3: Complete Application Installation Automation
+
+**Objective**: Fully automate tracker deployment including SSL certificates
+
+#### Current State
+
+- ✅ VM provisioning via cloud-init
+- ✅ Basic app setup (copy files, `.env` config, `docker compose up`)
+- ❌ SSL certificate generation
+- ❌ Crontab setup for renewals
+- ❌ Production hardening steps
+
+#### Tasks
+
+- [ ] Automate SSL certificate generation with Certbot
+- [ ] Set up automatic certificate renewal crontabs
+- [ ] Implement production hardening automation
+- [ ] Create comprehensive deployment validation script
+- [ ] Handle edge cases and error recovery
+
+#### Implementation Notes
+
+- Integrate with existing cloud-init setup
+- If Certbot automation requires manual interaction, document as the only manual step
+- Follow production setup guide: https://torrust.com/blog/deploying-torrust-to-production
+
+**Deliverable**: One-command deployment to production-ready state
+
+---
+
+### Phase 4: Hetzner Infrastructure Implementation
+
+**Objective**: Add Hetzner Cloud provider support and validate complete deployment
+
+#### Tasks
+
+- [ ] Research and add Hetzner Cloud OpenTofu provider
+- [ ] Create Hetzner-specific Terraform configurations
+- [ ] Implement Hetzner cloud-init adaptations
+- [ ] Test complete deployment pipeline on Hetzner
+- [ ] Configure provider-level firewall (optional, complementing VM firewall)
+- [ ] Validate tracker accessibility via IP (HTTP)
+
+#### Provider Firewall Consideration
+
+- VM firewall via cloud-init: ✅ Required
+- Provider firewall: 🤔 Optional additional security layer
+
+#### Validation
+
+- [ ] Deploy test VM on Hetzner
+- [ ] Verify all services start correctly
+- [ ] Test tracker functionality (announce, scrape)
+- [ ] Confirm firewall rules work correctly
+- [ ] Performance and connectivity testing
+
+**Deliverable**: Working Hetzner deployment with IP access
+
+---
+
+### Phase 5: Database Migration (Optional)
+
+**Objective**: Migrate existing tracker data from Digital Ocean SQLite to Hetzner MySQL
+
+#### Tasks
+
+- [ ] Export existing SQLite data from Digital Ocean instance
+- [ ] Create data transformation scripts (SQLite → MySQL)
+- [ ] Import data to new MySQL instance
+- [ ] Validate data integrity and completeness
+- [ ] Test tracker with migrated data
+
+**Note**: This step is optional and can be skipped for a fresh start
+
+---
+
+### Phase 6: Testing and Validation
+
+**Objective**: Comprehensive testing of the new Hetzner deployment
+
+#### Testing Areas
+
+- [ ] **Functional Testing**: All tracker endpoints work correctly
+- [ ] **Performance Testing**: Announce/scrape response times
+- [ ] **Integration Testing**: Index ↔ Tracker communication
+- [ ] **Monitoring**: Grafana dashboards show correct metrics
+- [ ] **SSL Testing**: HTTPS certificate generation and renewal
+- [ ] **Backup Testing**: Database backup and restore procedures
+
+#### Test Scenarios
+
+- [ ] Fresh torrent announce and scrape
+- [ ] High-load announce testing
+- [ ] Tracker restart with data persistence
+- [ ] Certificate renewal simulation
+- [ ] Firewall rule validation
+
+**Deliverable**: Fully validated production deployment
+
+---
+
+### Phase 7: Go Live
+
+**Objective**: Switch production traffic to Hetzner infrastructure
+
+#### Pre-Go-Live
+
+- [ ] Consider static IP allocation on Hetzner
+- [ ] Prepare DNS change procedures
+- [ ] Document rollback plan
+
+#### Go-Live Steps
+
+- [ ] Update DNS records to point to new Hetzner IP
+- [ ] Update Digital Ocean index configuration:
+  - Change tracker resolution from Docker service name to public domain
+  - Index will access tracker via public API instead of internal Docker network
+- [ ] Monitor traffic and error rates
+- [ ] Validate end-to-end functionality
+
+#### Post-Go-Live
+
+- [ ] Monitor system stability for 24-48 hours
+- [ ] Verify certificate auto-renewal works
+- [ ] Confirm backup procedures
+- [ ] Update documentation with new procedures
+
+**Deliverable**: Production traffic on Hetzner infrastructure
+
+---
+
+## Future Considerations
+
+### Dynamic Configuration (Future Work)
+
+Currently hardcoded in cloud-init:
+
+- Number of tracker instances (e.g., 2 UDP trackers on ports 6868, 6969)
+- Firewall port configurations
+- Service scaling parameters
+
+**Future Enhancement**: Inject dynamic configuration via template variables
+
+### Repository Template Usage
+
+This repository serves as a template for users deploying their own trackers. Current
+hardcoded configurations can be manually adapted, but future work could make this more
+dynamic.
+
+## Risk Mitigation
+
+### Rollback Plan
+
+- Keep Digital Ocean instance running until Hetzner deployment is fully validated
+- Maintain DNS rollback capability
+- Document emergency procedures
+
+### Testing Strategy
+
+- All changes tested locally before Hetzner deployment
+- Staged rollout with validation at each phase
+- Comprehensive testing before DNS switch
+
+## Success Criteria
+
+- [ ] Tracker accessible via HTTPS on Hetzner
+- [ ] MySQL database working with persistent data
+- [ ] Grafana monitoring functional
+- [ ] SSL certificates auto-renewing
+- [ ] Index successfully communicating with tracker
+- [ ] Performance equivalent to or better than Digital Ocean
+- [ ] 12-Factor App compliance achieved
+- [ ] One-command deployment working
diff --git a/project-words.txt b/project-words.txt
@@ -10,6 +10,7 @@ commoninit
 conntrack
 containerd
 CPUS
+crontabs
 dialout
 direnv
 dmacvicar
