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

Commit 58c7294

Browse files
josecelanojosecelano
committed
docs: [#10] add ADR-002 documenting Docker for all services decision
- Create comprehensive ADR documenting the decision to use Docker for all services including UDP tracker despite potential performance overhead - Document technical challenges with host networking and connection tracking - Reference related GitHub issues #27 and torrust#72 from torrust-demo repo - Update application README with Docker design decision section - Update twelve-factor refactor docs to reference new ADR - Update main README to list both ADRs with descriptions - Update cloud-init comments to clarify dependency installation purpose - Prioritize demo simplicity and consistency over peak performance
1 parent a2e0554 commit 58c7294

File tree

6 files changed

+272
-3
lines changed

6 files changed

+272
-3
lines changed

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,10 @@ make destroy # Clean up
108108

109109
- [Documentation Structure](docs/README.md) - Cross-cutting documentation
110110
- [Architecture Decisions](docs/adr/) - Design decisions and rationale
111+
- [ADR-001: Makefile Location](docs/adr/001-makefile-location.md) - Why the
112+
main Makefile is at repository root
113+
- [ADR-002: Docker for All Services](docs/adr/002-docker-for-all-services.md) -
114+
Why we use Docker for all services including UDP tracker
111115

112116
## 🛠️ Development
113117

‎application/README.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,3 +204,45 @@ Application documentation should cover:
204204
- Application-specific troubleshooting
205205

206206
See [`../infrastructure/`](../infrastructure/) for infrastructure-specific documentation.
207+
208+
## 🐳 Docker Design Decision
209+
210+
This demo repository uses **Docker containers for all services**, including the
211+
Torrust Tracker UDP component, even though this may not provide optimal
212+
performance for high-throughput UDP tracking operations.
213+
214+
### Why Docker for Everything?
215+
216+
The decision to use Docker for all services, including the performance-critical
217+
UDP tracker, prioritizes:
218+
219+
1. **Simplicity**: Single orchestration method (Docker Compose) for all services
220+
2. **Consistency**: Identical deployment process across environments
221+
3. **Maintainability**: Easier updates and dependency management
222+
4. **Documentation**: Clear, reusable examples for users
223+
5. **Demo Focus**: Emphasizes functionality demonstration over peak performance
224+
225+
### Performance Considerations
226+
227+
While Docker networking may introduce some overhead for UDP operations compared
228+
to running the tracker binary directly on the host, this trade-off aligns with
229+
the repository's primary goals:
230+
231+
- **Demo Environment**: Showcasing Torrust Tracker functionality
232+
- **Frequent Updates**: Easy deployment of new tracker versions
233+
- **User-Friendly**: Simple setup process for evaluation and testing
234+
235+
### Production Performance Optimization
236+
237+
For production deployments requiring maximum UDP performance, consider:
238+
239+
- Running the tracker binary directly on the host
240+
- Using host networking mode for containers
241+
- Implementing kernel-level network optimizations
242+
- Disabling connection tracking for UDP traffic
243+
244+
These optimizations will be covered in dedicated performance documentation
245+
outside this demo repository.
246+
247+
> **Reference**: See [ADR-002](../docs/adr/002-docker-for-all-services.md) for
248+
> the complete rationale behind this design decision.

‎docs/adr/002-docker-for-all-services.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# ADR-002: Use Docker for All Services Including UDP Tracker
2+
3+
## Status
4+
5+
Accepted
6+
7+
## Date
8+
9+
2025-01-07
10+
11+
## Context
12+
13+
The Torrust Tracker Demo repository provides a complete deployment environment for
14+
the Torrust Tracker, including the UDP tracker component, HTTP tracker, REST API,
15+
and supporting services (Prometheus, Grafana, MySQL/SQLite).
16+
17+
### Performance Considerations
18+
19+
UDP tracker performance is critical for BitTorrent operations, and several
20+
performance optimization approaches were considered:
21+
22+
1. **Host Network Mode**: Running UDP tracker containers with `--network=host`
23+
to avoid Docker networking overhead
24+
2. **Connection Tracking Disable**: Disabling `nf_conntrack` to reduce kernel
25+
overhead for UDP packet processing
26+
3. **Source Compilation**: Running the tracker binary directly on the host
27+
instead of using Docker containers
28+
29+
### Technical Challenges Identified
30+
31+
During investigation of performance optimizations, several issues were encountered:
32+
33+
1. **Connection Tracking vs Docker**: Docker networking appears to rely on
34+
connection tracking (`nf_conntrack`) for proper packet routing. Disabling
35+
connection tracking while using Docker containers resulted in networking
36+
issues.
37+
38+
2. **Host Mode Limitations**: While host networking mode worked, it created
39+
complications with service orchestration and port management in the demo
40+
environment.
41+
42+
3. **Complexity vs Benefit**: Performance optimizations added significant
43+
complexity to the deployment process and infrastructure management.
44+
45+
### Related Issues
46+
47+
This decision addresses problems documented in previous GitHub issues:
48+
49+
- [torrust/torrust-demo#27](https://github.com/torrust/torrust-demo/issues/27):
50+
Improve tracker performance by adjusting docker network configuration
51+
- [torrust/torrust-demo#72](https://github.com/torrust/torrust-demo/issues/72):
52+
Fix nf_conntrack table overflow causing UDP packet drops
53+
54+
## Decision
55+
56+
**Use Docker containers for all services in the Torrust Tracker Demo, including
57+
the UDP tracker, without host networking mode or connection tracking modifications.**
58+
59+
## Rationale
60+
61+
### Primary Goals Alignment
62+
63+
The Torrust Tracker Demo repository has specific primary objectives:
64+
65+
1. **Demo Environment Setup**: Provide a complete, working demonstration of
66+
Torrust Tracker functionality
67+
2. **Frequent Updates**: Update the demo environment regularly, ideally with
68+
every tracker release
69+
3. **Declarative Infrastructure**: Maintain Infrastructure as Code approach
70+
for reproducible deployments
71+
4. **Documentation Generation**: Serve as a reference implementation for
72+
deployment procedures
73+
74+
### Performance vs Simplicity Trade-off
75+
76+
While Docker networking may introduce some performance overhead compared to
77+
native host networking, the benefits outweigh the costs for this use case:
78+
79+
**Benefits of Docker Approach:**
80+
81+
- **Consistency**: All services use the same orchestration method
82+
- **Simplicity**: Single Docker Compose configuration manages all services
83+
- **Reproducibility**: Identical behavior across different environments
84+
- **Maintenance**: Easier updates and dependency management
85+
- **Documentation**: Clearer examples for users to follow
86+
- **Testing**: Simplified CI/CD and local testing procedures
87+
88+
**Performance Considerations:**
89+
90+
- The demo environment prioritizes functionality demonstration over peak performance
91+
- Users requiring maximum performance can reference this implementation and
92+
optimize for their specific production needs
93+
- Performance optimizations can be documented separately without complicating
94+
the base demo
95+
96+
### Future Performance Documentation
97+
98+
Performance optimization will be addressed through:
99+
100+
1. **Dedicated Documentation**: Separate guides for production performance tuning
101+
2. **Configuration Examples**: Performance-focused configuration templates
102+
3. **Best Practices**: Documentation of optimization techniques and trade-offs
103+
4. **Potential Repositories**: Specialized repositories focused on high-performance
104+
deployments
105+
106+
## Consequences
107+
108+
### Positive Consequences
109+
110+
- **Simplified Deployment**: Single orchestration method for all services
111+
- **Better Documentation**: Clear, consistent examples for users
112+
- **Easier Maintenance**: Streamlined update procedures
113+
- **Improved Testing**: Consistent test environments
114+
- **Faster Development**: Reduced complexity in infrastructure management
115+
116+
### Negative Consequences
117+
118+
- **Performance Overhead**: Some UDP tracker performance impact from Docker networking
119+
- **Resource Usage**: Additional container overhead compared to native binaries
120+
- **Networking Complexity**: Docker networking abstractions may obscure network issues
121+
122+
### Mitigation Strategies
123+
124+
1. **Clear Documentation**: Document the performance trade-offs explicitly
125+
2. **Performance Guidelines**: Provide separate documentation for production
126+
performance optimization
127+
3. **Configuration Examples**: Include performance-tuned configuration examples
128+
4. **Monitoring**: Include comprehensive monitoring to identify performance issues
129+
130+
### Future Considerations
131+
132+
- Monitor for significant performance issues in demo environment
133+
- Re-evaluate if Docker networking becomes a major limitation
134+
- Consider hybrid approaches for specific production use cases
135+
- Provide migration guides for users who need maximum performance
136+
137+
## Alternatives Considered
138+
139+
### Alternative 1: Host Network Mode
140+
141+
**Description**: Run UDP tracker with `--network=host`
142+
143+
**Pros**:
144+
145+
- Better network performance
146+
- Reduced networking overhead
147+
- Direct access to host network interfaces
148+
149+
**Cons**:
150+
151+
- Port conflicts with host services
152+
- Reduced container isolation
153+
- Complications with service discovery
154+
- More complex firewall configuration
155+
156+
**Decision**: Rejected due to increased complexity and orchestration challenges
157+
158+
### Alternative 2: Native Binary Deployment
159+
160+
**Description**: Compile and run tracker binary directly on host
161+
162+
**Pros**:
163+
164+
- Maximum performance
165+
- No container overhead
166+
- Direct kernel network access
167+
168+
**Cons**:
169+
170+
- Complex dependency management
171+
- Platform-specific build requirements
172+
- Reduced deployment consistency
173+
- More complex update procedures
174+
- Breaking changes to current infrastructure
175+
176+
**Decision**: Rejected due to complexity and maintenance burden
177+
178+
### Alternative 3: Hybrid Approach
179+
180+
**Description**: Use Docker for supporting services, native binary for tracker
181+
182+
**Pros**:
183+
184+
- Performance optimization for critical component
185+
- Maintained orchestration for supporting services
186+
187+
**Cons**:
188+
189+
- Increased complexity
190+
- Mixed deployment methods
191+
- More complex CI/CD pipelines
192+
- Inconsistent documentation examples
193+
194+
**Decision**: Rejected due to increased complexity and mixed approaches
195+
196+
### Alternative 4: Conditional Deployment
197+
198+
**Description**: Support both Docker and native deployment modes
199+
200+
**Pros**:
201+
202+
- User choice for performance vs simplicity
203+
- Flexibility for different use cases
204+
205+
**Cons**:
206+
207+
- Significant maintenance burden
208+
- Complex documentation
209+
- Multiple testing matrices
210+
- Potential for configuration drift
211+
212+
**Decision**: Rejected due to maintenance complexity
213+
214+
## References
215+
216+
- [Torrust Tracker Documentation](https://docs.rs/torrust-tracker/)
217+
- [GitHub Issue #27: Docker Network Configuration](https://github.com/torrust/torrust-demo/issues/27)
218+
- [GitHub Issue #72: nf_conntrack Overflow](https://github.com/torrust/torrust-demo/issues/72)

‎infrastructure/cloud-init/user-data.yaml.tpl‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,9 @@ packages:
5252
- ufw
5353
- fail2ban
5454
- unattended-upgrades
55-
# Torrust Tracker dependencies for future source compilation
55+
# Torrust Tracker dependencies for potential source compilation
5656
# Currently using Docker, but planning to compile from source for better performance
57+
# in production environments (see ADR-002)
5758
- pkg-config
5859
- libssl-dev
5960
- make
@@ -202,7 +203,7 @@ final_message: |
202203
- Firewall: UFW enabled with proper SSH rules
203204
- Security: Automatic updates enabled
204205
- Torrust Tracker dependencies: pkg-config, libssl-dev, make, build-essential, libsqlite3-dev, sqlite3
205-
(for future source compilation)
206+
(for potential source compilation in production environments)
206207

207208
SSH Access:
208209
- SSH Key: ssh torrust@VM_IP

‎infrastructure/docs/refactoring/twelve-factor-refactor/README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,11 @@ From the official Torrust Tracker documentation, we need to account for:
4040
#### Docker vs Source Compilation
4141

4242
- **Current**: Using Docker images (torrust/tracker:develop)
43-
- **Future**: Plans to compile from source for better performance
43+
- **Future Plans**: Considering source compilation for production performance optimization
4444
- **Dependencies**: pkg-config, libssl-dev, make, build-essential, libsqlite3-dev
45+
- **Demo Repository Decision**: Uses Docker for all services to prioritize simplicity,
46+
consistency, and frequent updates over peak performance
47+
(see [ADR-002](../../../docs/adr/002-docker-for-all-services.md))
4548

4649
### Twelve-Factor Violations Identified
4750

‎project-words.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ cdrom
77
certbot
88
cloudinit
99
commoninit
10+
conntrack
1011
containerd
1112
CPUS
1213
dialout

0 commit comments

Comments
 (0)