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

Commit f6d9b8e

Browse files
josecelanojosecelano
committed
docs: [#28] add ADR-008 staging domain strategy for Hetzner deployment
- Document selection of staging-torrust-demo.com for staging environment - Analyze HSTS constraints with .dev TLD and domain alternatives - Provide comprehensive rationale for domain naming strategy - Include implementation guidance for DNS and environment configuration - Update ADR index with new architectural decision record Resolves domain strategy decision for Phase 4 Hetzner infrastructure implementation.
1 parent 290b070 commit f6d9b8e

File tree

2 files changed

+247
-1
lines changed

2 files changed

+247
-1
lines changed

‎docs/adr/008-staging-domain-strategy-for-hetzner-deployment.md‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# ADR-008: Staging Domain Strategy for Hetzner Cloud Deployment
2+
3+
## Status
4+
5+
Accepted
6+
7+
## Date
8+
9+
2025-08-07
10+
11+
## Context
12+
13+
During the implementation of Hetzner Cloud infrastructure for staging and production
14+
environments, we needed to decide on a domain naming strategy that would:
15+
16+
1. **Clearly distinguish environments** - Avoid confusion between staging and production
17+
2. **Enable flexible testing** - Allow testing of various nginx configurations without browser interference
18+
3. **Maintain production similarity** - Keep staging as close to production as possible
19+
4. **Avoid HSTS constraints** - Enable HTTP-only testing when needed for configuration validation
20+
21+
### Initial Domain Strategy
22+
23+
Originally, we considered using `torrust-demo.dev` for staging and `torrust-demo.com`
24+
for production. However, this approach presented several challenges:
25+
26+
#### HSTS Preload Issues with .dev TLD
27+
28+
The `.dev` top-level domain is included in the browser HSTS preload list, which means:
29+
30+
- **Automatic HTTPS enforcement**: Browsers automatically redirect all HTTP requests to HTTPS
31+
- **Testing limitations**: Cannot test HTTP-only configurations or mixed HTTP/HTTPS scenarios
32+
- **Certificate dependency**: Requires valid SSL certificates for any testing
33+
- **Configuration constraints**: Limits flexibility for nginx configuration testing
34+
35+
#### Alternative Domains Considered
36+
37+
1. **`torrust-demo.org`** - Rejected because:
38+
39+
- Could be confused with an official organization website
40+
- Appears more "legitimate" than production domain
41+
- May mislead users about project official status
42+
43+
2. **`test-torrust-demo.com`** - Considered but less explicit
44+
45+
3. **`staging-torrust-demo.com`** - Selected for clear environment identification
46+
47+
## Decision
48+
49+
We will use **`staging-torrust-demo.com`** for the staging environment and
50+
**`torrust-demo.com`** for production.
51+
52+
### Domain Architecture
53+
54+
- **Production**: `torrust-demo.com`
55+
56+
- `tracker.torrust-demo.com` - Main tracker services
57+
- `grafana.torrust-demo.com` - Monitoring dashboard
58+
59+
- **Staging**: `staging-torrust-demo.com`
60+
- `tracker.staging-torrust-demo.com` - Staging tracker services
61+
- `grafana.staging-torrust-demo.com` - Staging monitoring dashboard
62+
63+
## Rationale
64+
65+
### 1. Clear Environment Identification
66+
67+
The explicit "staging" prefix provides immediate clarity:
68+
69+
- **Unambiguous purpose**: Anyone accessing the domain knows it's a staging environment
70+
- **Prevents confusion**: No possibility of mistaking staging for production
71+
- **Team communication**: Clear reference in documentation, tickets, and discussions
72+
- **Audit trails**: Easy to identify staging vs production in logs and monitoring
73+
74+
### 2. Flexible Configuration Testing
75+
76+
Using a `.com` domain (not `.dev`) enables comprehensive testing scenarios:
77+
78+
- **HTTP-only testing**: Can test nginx configurations without SSL certificates
79+
- **Mixed HTTP/HTTPS**: Can validate dual server configurations
80+
- **Redirect testing**: Can test various redirect scenarios without browser interference
81+
- **Security header testing**: Can validate CSP, HSTS, and other security policies
82+
83+
### 3. Production Similarity
84+
85+
The domain structure closely mirrors production:
86+
87+
- **Same TLD**: Both use `.com` avoiding TLD-specific behaviors
88+
- **Same subdomain pattern**: Consistent `tracker.` and `grafana.` prefixes
89+
- **Same DNS behavior**: No special browser treatments or preload lists
90+
- **Same certificate requirements**: Allows testing Let's Encrypt workflows
91+
92+
### 4. Infrastructure Consistency
93+
94+
The naming convention aligns with our infrastructure patterns:
95+
96+
- **Environment prefixing**: Follows cloud resource naming conventions
97+
- **DNS management**: Consistent pattern for DNS automation
98+
- **Certificate management**: Clear separation of staging and production certificates
99+
- **Monitoring separation**: Distinct monitoring targets for each environment
100+
101+
### 5. Professional Standards
102+
103+
The naming follows industry best practices:
104+
105+
- **Standard convention**: `staging-` prefix is widely recognized
106+
- **Corporate environments**: Matches enterprise staging environment patterns
107+
- **DevOps workflows**: Integrates well with CI/CD and deployment automation
108+
- **Documentation clarity**: Self-documenting domain purpose
109+
110+
## Implementation
111+
112+
### DNS Configuration
113+
114+
Both domains will use the same floating IP infrastructure:
115+
116+
```text
117+
# Production DNS (torrust-demo.com)
118+
tracker.torrust-demo.com A 78.47.140.132
119+
grafana.torrust-demo.com A 78.47.140.132
120+
121+
# Staging DNS (staging-torrust-demo.com)
122+
tracker.staging-torrust-demo.com A 78.47.140.132
123+
grafana.staging-torrust-demo.com A 78.47.140.132
124+
```
125+
126+
### Environment Configuration
127+
128+
```bash
129+
# Production environment
130+
TRACKER_DOMAIN=tracker.torrust-demo.com
131+
GRAFANA_DOMAIN=grafana.torrust-demo.com
132+
133+
# Staging environment
134+
TRACKER_DOMAIN=tracker.staging-torrust-demo.com
135+
GRAFANA_DOMAIN=grafana.staging-torrust-demo.com
136+
```
137+
138+
### SSL Certificate Strategy
139+
140+
- **Staging**: Can use self-signed, Let's Encrypt staging, or production certificates
141+
- **Production**: Let's Encrypt production certificates
142+
- **Testing flexibility**: Staging can test various certificate scenarios
143+
144+
## Benefits
145+
146+
### Development Workflow
147+
148+
- **Clear targeting**: Developers know exactly which environment they're accessing
149+
- **Safe testing**: No risk of accidentally affecting production
150+
- **Comprehensive validation**: Can test all nginx configuration scenarios
151+
- **Browser compatibility**: No TLD-specific browser behaviors
152+
153+
### Operations
154+
155+
- **Monitoring clarity**: Distinct targets for staging and production monitoring
156+
- **Log separation**: Clear environment identification in logs and alerts
157+
- **Certificate management**: Separate certificate lifecycles
158+
- **DNS management**: Clear zone separation
159+
160+
### Security
161+
162+
- **Environment isolation**: Clear separation reduces cross-environment risks
163+
- **Certificate validation**: Can test certificate workflows safely
164+
- **Security header testing**: Can validate security configurations
165+
- **Access control**: Clear identification for access policies
166+
167+
## Consequences
168+
169+
### Positive
170+
171+
- **Eliminates confusion** between staging and production environments
172+
- **Enables comprehensive testing** of nginx configurations without browser interference
173+
- **Maintains production similarity** while providing staging flexibility
174+
- **Follows industry standards** for environment naming
175+
- **Supports flexible SSL testing** scenarios
176+
177+
### Negative
178+
179+
- **Additional DNS zone required** for `staging-torrust-demo.com` domain
180+
- **Certificate management complexity** for separate domain (though this enables testing)
181+
- **Longer domain names** may be less convenient for manual access
182+
183+
### Neutral
184+
185+
- **Domain registration cost** for staging domain (minimal operational expense)
186+
- **DNS propagation** timing same as any new domain setup
187+
- **Documentation updates** required for new domain references
188+
189+
## Alternatives Considered
190+
191+
### Alternative 1: torrust-demo.dev (Rejected)
192+
193+
**Pros**: Shorter domain, clear development purpose
194+
**Cons**: HSTS preload list forces HTTPS, limits testing flexibility
195+
196+
### Alternative 2: torrust-demo.org (Rejected)
197+
198+
**Pros**: No HSTS constraints, flexible testing
199+
**Cons**: Could be confused with official organization, appears more "official" than production
200+
201+
### Alternative 3: test-torrust-demo.com (Considered)
202+
203+
**Pros**: Clear testing purpose, no HSTS constraints
204+
**Cons**: Less explicit than "staging", could be confused with unit testing
205+
206+
## Related Decisions
207+
208+
- [ADR-006: SSL Certificate Generation Strategy](006-ssl-certificate-generation-strategy.md) -
209+
SSL certificate management approach
210+
- [ADR-007: Two-Level Environment Variable Structure](007-two-level-environment-variable-structure.md)
211+
- Environment configuration separation
212+
213+
## References
214+
215+
- [HSTS Preload List](https://hstspreload.org/) - Browser HSTS enforcement documentation
216+
- [Hetzner Cloud Documentation](https://docs.hetzner.cloud/) - DNS and floating IP management
217+
- [nginx Configuration Documentation](../infrastructure/config/templates/application/nginx/README.md)
218+
- HTTP/HTTPS redirect policies
219+
220+
## Future Considerations
221+
222+
- **Multi-region staging**: Domain pattern can extend to regional staging environments
223+
- **Feature branch environments**: Pattern supports feature-specific staging domains
224+
- **Load testing environments**: Can create performance testing specific domains
225+
- **Customer demo environments**: Pattern supports customer-specific demo instances
226+
227+
## Validation
228+
229+
This decision enables the complete nginx configuration testing scenarios:
230+
231+
- ✅ HTTP-only access (no browser HTTPS redirect)
232+
- ✅ HTTPS-only access with proper certificates
233+
- ✅ Dual HTTP/HTTPS server configuration
234+
- ✅ Manual redirect enablement testing
235+
- ✅ Security header validation
236+
- ✅ Let's Encrypt ACME challenge testing
237+
- ✅ Certificate renewal automation testing
238+
239+
The staging domain provides the flexibility needed for comprehensive configuration
240+
validation while maintaining clear environment separation and production similarity.

‎docs/adr/README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,10 +135,16 @@ These are separate infrastructure concerns and should be documented separately:
135135
- [ADR-006: SSL Certificate Generation Strategy]
136136
(006-ssl-certificate-generation-strategy.md) -
137137
Generate certificates per deployment vs reusing certificates
138+
- [ADR-007: Two-Level Environment Variable Structure]
139+
(007-two-level-environment-variable-structure.md) -
140+
Security-focused separation of infrastructure and container variables
141+
- [ADR-008: Staging Domain Strategy for Hetzner Deployment]
142+
(008-staging-domain-strategy-for-hetzner-deployment.md) -
143+
Selection of staging-torrust-demo.com for staging environment
138144

139145
### 📊 ADR Statistics
140146

141-
- **Total ADRs**: 6
147+
- **Total ADRs**: 8
142148
- **Status**: All Accepted
143149
- **Coverage**: Infrastructure (3), Application (2), Development Workflow (1)
144150

0 commit comments

Comments
 (0)