Skip to content
This repository was archived by the owner on Oct 10, 2025. It is now read-only.

Commit ec4a2dd

Browse files
josecelanojosecelano
committed
feat: [#31] declare repository as frozen PoC and establish redesign scaffolding
- Declare current repository status as completed proof of concept - Mark repository as frozen with active development moved to redesign initiative - Set up engineering process for greenfield redesign under docs/redesign/ Documentation Updates: - Update README.md with frozen PoC status and redesign initiative reference - Update .github/copilot-instructions.md with frozen status and contributor guidance - Add project-words.txt entries for redesign terminology Redesign Scaffolding: - Create docs/redesign/ structure with 5-phase engineering process (phases 0-4) - Establish docs/redesign/phase0-goals/ for strategic project documentation - Move project-goals-and-scope.md from phase1-requirements to phase0-goals - Add docs/redesign/README.md with comprehensive phase structure documentation - Initialize phase1-requirements/ with architectural and technical requirement documents This establishes clear separation between: 1. Historical PoC implementation (frozen for reference) 2. Active redesign engineering process (docs/redesign/) 3. Strategic goals (phase 0) vs technical requirements (phase 1+) Resolves: #31
1 parent e145f12 commit ec4a2dd

File tree

8 files changed

+722
-11
lines changed

8 files changed

+722
-11
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -49,23 +49,37 @@
4949

5050
## 📋 Document Maintenance
5151

52-
**Torrust Tracker Demo** is the complete production deployment configuration for running a live [Torrust Tracker](https://github.com/torrust/torrust-tracker) instance. This repository provides:
52+
> ⚠️ **REPOSITORY STATUS: This repository is now FROZEN as a historical Proof of Concept (PoC).**
53+
>
54+
> - No new features or major refactors will be implemented here.
55+
> - Active engineering has moved to a **greenfield redesign initiative** documented under
56+
> `docs/redesign/` ([Issue #31](https://github.com/torrust/torrust-tracker-demo/issues/31)).
57+
> - Only documentation, requirements, and architecture specification updates are accepted in
58+
> this repo.
59+
>
60+
> If you are evaluating how Torrust Tracker _will_ be deployed going forward, start with: `docs/redesign/README.md`.
61+
62+
**Torrust Tracker Demo** is a historical Proof of Concept that demonstrates a complete production deployment configuration for running a live [Torrust Tracker](https://github.com/torrust/torrust-tracker) instance. This repository provides:
5363

5464
- **Production deployment** configurations for Hetzner cloud infrastructure
5565
- **Local testing environment** using KVM/libvirt virtualization
5666
- **Infrastructure as Code** approach using OpenTofu/Terraform and cloud-init
5767
- **Monitoring setup** with Grafana dashboards and Prometheus metrics
5868
- **Automated deployment** scripts and Docker Compose configurations
5969

70+
This PoC still demonstrates a full twelve-factor style deployment (infrastructure provisioning + application lifecycle) and remains a reference for baseline behaviors. Its documentation is being actively curated to extract reusable requirements for the next-generation implementation.
71+
6072
### Current Major Initiative
6173

62-
We are migrating the tracker to a new infrastructure on Hetzner, involving:
74+
**Legacy Context (Superseded)**: We were migrating the tracker to a new infrastructure on Hetzner, involving:
6375

6476
- Running the tracker binary directly on the host for performance
6577
- Using Docker for supporting services (Nginx, Prometheus, Grafana, MySQL)
6678
- Migrating the database from SQLite to MySQL
6779
- Implementing Infrastructure as Code for reproducible deployments
6880

81+
**Current Focus**: Active engineering has moved to a **greenfield redesign initiative** documented under `docs/redesign/` ([Issue #31](https://github.com/torrust/torrust-tracker-demo/issues/31)). This repository is now frozen and serves as a historical reference.
82+
6983
## 🏗️ Twelve-Factor Architecture
7084

7185
This project implements a complete twelve-factor app architecture with clear separation between infrastructure provisioning and application deployment:
@@ -692,7 +706,9 @@ When providing assistance:
692706
- Prioritize security and best practices
693707
- Test infrastructure changes locally before suggesting them
694708
- Provide clear explanations and documentation
695-
- Consider the migration to Hetzner infrastructure in suggestions
709+
- **CRITICAL**: Understand this repository's frozen status - focus on documentation, requirements extraction, and architecture specification only
710+
- **NEW FEATURES**: Direct users to the redesign initiative in `docs/redesign/` for new functionality discussions
711+
- **INFRASTRUCTURE CHANGES**: Legacy infrastructure should only be modified for documentation purposes or critical fixes
696712
- **CRITICAL**: Respect the three-layer testing architecture (see Testing Requirements above)
697713

698714
#### Testing Layer Separation (CRITICAL)

‎README.md‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,28 @@
11
[![Testing](https://github.com/torrust/torrust-tracker-demo/actions/workflows/testing.yml/badge.svg)](https://github.com/torrust/torrust-tracker-demo/actions/workflows/testing.yml)
22

3-
# Torrust Tracker Demo
3+
# Torrust Tracker Demo (Frozen Proof of Concept)
44

5-
This repo contains all the configuration needed to run the live Torrust Tracker demo.
5+
> ⚠️ REPOSITORY STATUS: **This repository is now FROZEN as a historical Proof of Concept (PoC).**
6+
>
7+
> - No new features or major refactors will be implemented here.
8+
> - Active engineering has moved to a **greenfield redesign initiative** documented under
9+
> `docs/redesign/` ([Issue #31](https://github.com/torrust/torrust-tracker-demo/issues/31)).
10+
> - Only documentation, requirements, and architecture specification updates are accepted in
11+
> this repo.
12+
>
13+
> If you are evaluating how Torrust Tracker _will_ be deployed going forward, start with: `docs/redesign/README.md`.
14+
15+
This PoC still demonstrates a full twelve-factor style deployment (infrastructure provisioning +
16+
application lifecycle) and remains a reference for baseline behaviors. Its documentation is
17+
being actively curated to extract reusable requirements for the next-generation implementation.
618

7-
It's also used to track issues in production.
19+
Historic description (legacy context retained below for reference):
20+
21+
This repo contains all the configuration needed to run the live Torrust Tracker demo.
822

9-
> IMPORTANT: We are in the process of [splitting the Torrust Demo repo into
10-
> two repos](https://github.com/torrust/torrust-demo/issues/79). This will
11-
> allow us to deploy both services independently and it would make easier for
12-
> users who only want to setup the tracker to re-use this setup. The content
13-
> of this repo may change drastically in the future.
23+
> (Legacy notice) We were in the process of
24+
> [splitting the Torrust Demo repo into two repos](https://github.com/torrust/torrust-demo/issues/79).
25+
> That plan has been superseded by the broader redesign captured in Issue #31.
1426
1527
## 🏗️ Repository Structure
1628

‎docs/redesign/README.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Redesign Docs (Freeze Mode)
2+
3+
> **STATUS: DESIGN FREEZE** – Code here stays as-is. We are only improving the redesign
4+
> docs until the new implementation repo is created.
5+
6+
These docs (Issue **#31**) explain where we are going and why. Keep it light, clear and
7+
useful for future contributors.
8+
9+
## What You Can Do Now
10+
11+
| You want to… | Allowed? | How |
12+
| ------------------------------------------------- | -------- | ----------------------------------------------- |
13+
| Improve existing redesign docs | ✅ | Edit files under `docs/redesign/` |
14+
| Add a missing focused requirement (e.g. firewall) | ✅ | New file + link it here + reference #31 |
15+
| Add an ADR | ✅ | Follow ADR format; keep it short & scoped |
16+
| Change PoC code / refactor | ❌ | Archived; will rebuild clean later |
17+
| Bump dependencies / tooling | ❌ | Unless a security issue (then open issue first) |
18+
| Modify scripts or tests | ❌ | Only if a doc would be incorrect otherwise |
19+
20+
If something outside the list is really needed (security/legal), open an issue and we’ll list it below.
21+
22+
## Current Focus
23+
24+
Closing **Phase 1 (Requirements)**. Last gap just filled:
25+
26+
- Dynamic firewall / network exposure management → [`phase1-requirements/firewall-dynamic-handling.md`](./phase1-requirements/firewall-dynamic-handling.md)
27+
28+
After a quick review we move to Phase 2 (measure current behaviour: performance, state, operational toil).
29+
30+
## Folder Map
31+
32+
| Folder | Purpose |
33+
| ---------------------- | ------------------------------------------ |
34+
| `phase0-goals/` | Project goals & scope |
35+
| `phase1-requirements/` | Agreed requirements & technical details |
36+
| `phase2-analysis/` | (Next) What the PoC actually does / limits |
37+
| `phase3-design/` | Future architecture sketches & decisions |
38+
| `phase4-planning/` | Milestones & rollout plan |
39+
| `community-input/` | Collected suggestions & feedback |
40+
41+
## Simple 5-Phase Flow
42+
43+
0. Goals & scope (what we're trying to achieve)
44+
1. Requirements (what matters technically)
45+
2. Analyse current PoC (truth vs assumptions)
46+
3. Design new solution
47+
4. Plan build & migration
48+
49+
## Next Up (Short List)
50+
51+
| Item | Phase | Status |
52+
| --------------------------------------------------- | ----- | -------------- |
53+
| Runtime state & persistence inventory | 2 | Planned |
54+
| Performance baseline (throughput/latency/resources) | 2 | Planned |
55+
| Dynamic firewall ADR (pick final approach) | 1 | Pending review |
56+
| Deployment topology options | 3 | Drafting |
57+
| Build graph / incremental strategy | 3 | Backlog |
58+
59+
## Related
60+
61+
- Master issue: [#31 – Redesign](https://github.com/torrust/torrust-tracker-demo/issues/31)
62+
63+
## Exceptional Changes (none)
64+
65+
_Empty. Add entries here only if an approved out‑of‑scope change happens._

‎docs/redesign/phase0-goals/project-goals-and-scope.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Project Goals and Scope
2+
3+
**Category**: Product Vision and Scope
4+
**Priority**: Critical
5+
**Status**: Draft
6+
7+
## Primary Goal
8+
9+
**Enable system administrators to provision a virtual machine and set up the Torrust tracker in an
10+
almost fully automated way (90% automation), providing excellent user experience and lowering
11+
the barrier to tracker adoption.**
12+
13+
### Success Criteria
14+
15+
- 90% automation of the installation process
16+
- Clear, intuitive user experience for system administrators
17+
- Significantly reduced time-to-deployment compared to manual installation
18+
- Comprehensive documentation that guides users through the entire process
19+
- Minimal technical expertise required beyond basic system administration
20+
21+
## Secondary Goals
22+
23+
### Documentation and Knowledge Transfer
24+
25+
**Comprehensive documentation of tracker installation requirements including:**
26+
27+
- System dependencies and prerequisites
28+
- Host system configuration best practices
29+
- Firewall configuration and security requirements
30+
- Performance tuning recommendations
31+
- Troubleshooting guides and common issues
32+
33+
### Benefits
34+
35+
- Reduces support burden through self-service documentation
36+
- Establishes best practices for tracker deployment
37+
- Enables community contribution to installation knowledge
38+
- Provides reference for manual installations when automation isn't sufficient
39+
40+
## Long-Term Goals
41+
42+
### Multi-Provider Support
43+
44+
**Provide support for multiple cloud hosting providers to maximize deployment flexibility.**
45+
46+
#### Planned Providers
47+
48+
- Local virtualization (libvirt/KVM) - _Currently implemented_
49+
- Cloud providers (AWS, DigitalOcean, Hetzner, etc.) - _Future roadmap_
50+
51+
#### Benefits
52+
53+
- User choice and flexibility in hosting platform
54+
- Reduced vendor lock-in
55+
- Market expansion to different cloud ecosystems
56+
- Resilience against provider-specific limitations
57+
58+
## Explicit Out-of-Scope
59+
60+
### Server Maintenance
61+
62+
**Rationale**: This is a one-execution installer focused on initial deployment.
63+
64+
- **Not included**: Post-installation system updates
65+
- **Not included**: Application updates and patching
66+
- **Not included**: Ongoing maintenance automation
67+
- **Alternative**: Users handle maintenance through standard system administration practices
68+
69+
### Dynamic Scaling
70+
71+
**Rationale**: Torrust tracker does not support horizontal scaling architecturally.
72+
73+
- **Not included**: Auto-scaling based on load
74+
- **Not included**: Multi-instance load balancing
75+
- **Not included**: Automatic migration to larger servers
76+
- **Alternative**: Manual migration by deploying to new infrastructure and migrating data
77+
78+
### Migration Between Providers
79+
80+
**Rationale**: Complex cross-provider migration is beyond project scope.
81+
82+
- **Not included**: Automated provider-to-provider migration
83+
- **Not included**: Data migration tooling
84+
- **Not included**: Cross-provider compatibility layers
85+
- **Alternative**: Fresh deployment on new provider with manual data migration
86+
87+
### 100% Automation
88+
89+
**Rationale**: Perfect automation has diminishing returns for a typically one-time installation.
90+
91+
- **Acceptable**: 10% manual steps for complex or rarely-automated tasks
92+
- **Acceptable**: Manual verification steps for security-critical operations
93+
- **Acceptable**: Provider-specific manual configuration where APIs are insufficient
94+
- **Focus**: Automate the 90% that provides the most value
95+
96+
## Target Audience
97+
98+
### Primary Users
99+
100+
- **System Administrators**: Setting up tracker infrastructure
101+
- **DevOps Engineers**: Integrating tracker deployment into existing workflows
102+
- **Self-hosters**: Individuals running personal tracker instances
103+
104+
### User Characteristics
105+
106+
- Basic understanding of Linux system administration
107+
- Familiarity with command-line interfaces
108+
- Understanding of networking concepts (DNS, firewalls, etc.)
109+
- May or may not have cloud provider experience
110+
111+
## Value Proposition
112+
113+
### For Users
114+
115+
- **Reduced Complexity**: Streamlined installation process
116+
- **Time Savings**: Hours reduced to minutes for deployment
117+
- **Reliability**: Tested, repeatable deployment process
118+
- **Flexibility**: Choice of hosting providers and configurations
119+
120+
### For Torrust Ecosystem
121+
122+
- **Adoption**: Lower barriers increase user base
123+
- **Quality**: Standardized deployments reduce support issues
124+
- **Community**: Enables focus on tracker features rather than deployment
125+
126+
## Measurement Criteria
127+
128+
### Quantitative Metrics
129+
130+
- **Deployment Time**: From start to working tracker (target: < 30 minutes)
131+
- **Automation Percentage**: Automated steps vs total steps (target: 90%)
132+
- **Success Rate**: Successful deployments vs attempted deployments
133+
- **Documentation Coverage**: Percentage of installation scenarios documented
134+
135+
### Qualitative Metrics
136+
137+
- **User Feedback**: Ease of use and clarity of process
138+
- **Community Adoption**: Usage in community deployments
139+
- **Support Reduction**: Fewer installation-related support requests
140+
141+
---
142+
143+
**Note**: This scope definition emerged from lessons learned during the proof of concept phase
144+
and community feedback about deployment complexity.

0 commit comments

Comments
 (0)