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

Commit bc9a9e2

Browse files
josecelanojosecelano
committed
feat: add git status warning and environment config documentation
- Add comprehensive README to infrastructure/config/environments/ explaining git archive deployment behavior - Add git status check to deployment script that warns about uncommitted changes - Explains why E2E tests might fail when template changes aren't committed - Documents git archive benefits for production safety and reproducibility - Provides troubleshooting guide for configuration deployment issues - Includes best practices for development and production workflows
1 parent 15e142d commit bc9a9e2

File tree

2 files changed

+271
-0
lines changed

2 files changed

+271
-0
lines changed

‎infrastructure/config/environments/README.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Environment Configuration Templates
2+
3+
This directory contains environment-specific configuration templates that are processed
4+
during deployment to generate the final configuration files.
5+
6+
## Files
7+
8+
- `local.env.tpl` - Local development environment template
9+
- `production.env.tpl` - Production environment template (requires manual setup)
10+
11+
## Template Processing
12+
13+
Templates use environment variable substitution (`envsubst`) to generate final
14+
configuration files:
15+
16+
```bash
17+
# Templates are processed like this:
18+
envsubst < local.env.tpl > local.env
19+
envsubst < production.env.tpl > production.env # (after manual setup)
20+
```
21+
22+
## Critical Deployment Behavior
23+
24+
### The Git Archive Issue
25+
26+
**IMPORTANT:** When you modify templates in this folder and run E2E tests, the tests
27+
might fail if they depend on the new values. This happens due to how the application
28+
deployment process works:
29+
30+
1. **Infrastructure Provisioning**: New VM is created
31+
2. **Code Deployment**: Git archive is copied to VM (`git archive HEAD`)
32+
3. **Configuration Generation**: Templates are processed on the VM
33+
34+
### The Problem
35+
36+
**`git archive` only includes committed changes, not your working tree changes.**
37+
38+
This means:
39+
40+
- ✅ If you modify templates and **commit** them, E2E tests will use the new values
41+
- ❌ If you modify templates but **don't commit** them, E2E tests will use the old
42+
committed values
43+
44+
### Example Scenario
45+
46+
```bash
47+
# 1. You modify local.env.tpl to change TRACKER_ADMIN_TOKEN
48+
vim infrastructure/config/environments/local.env.tpl
49+
50+
# 2. You run E2E tests without committing
51+
make test-e2e # ❌ FAILS - Uses old token from git archive
52+
53+
# 3. You commit your changes
54+
git add infrastructure/config/environments/local.env.tpl
55+
git commit -m "update token"
56+
57+
# 4. You run E2E tests again
58+
make test-e2e # ✅ PASSES - Uses new token from git archive
59+
```
60+
61+
## Why Git Archive?
62+
63+
The deployment process uses `git archive` for several important reasons:
64+
65+
### Development Benefits
66+
67+
- **Clean Deployment**: Only committed, tested changes are deployed
68+
- **Excludes Local Files**: Doesn't copy `.env` files, build artifacts, or local storage
69+
- **Reproducible**: Same git commit always produces the same deployment
70+
- **Fast**: Compressed archive transfer is faster than full directory sync
71+
72+
### Production Safety
73+
74+
- **Version Control**: Only committed code reaches production
75+
- **No Accidental Deployments**: Prevents deploying uncommitted debug code or secrets
76+
- **Audit Trail**: Clear link between deployments and git commits
77+
- **Rollback Capability**: Easy to redeploy any previous commit
78+
79+
## Best Practices
80+
81+
### For Development (E2E Testing)
82+
83+
1. **Always commit template changes before running E2E tests**:
84+
85+
```bash
86+
git add infrastructure/config/environments/
87+
git commit -m "update configuration templates"
88+
make test-e2e
89+
```
90+
91+
2. **Check git status before testing**:
92+
93+
```bash
94+
git status # Should show "working tree clean"
95+
make test-e2e
96+
```
97+
98+
### For Production Deployment
99+
100+
1. **Never modify templates directly in production**
101+
2. **Always test changes in development first**
102+
3. **Use proper git workflow** (feature branches, reviews, etc.)
103+
4. **Verify configuration after deployment**
104+
105+
## Alternative Approaches Considered
106+
107+
### Option 1: Copy Working Tree
108+
109+
```bash
110+
# Instead of: git archive HEAD | tar -xz
111+
rsync -av --exclude='.git' . vm:/path/
112+
```
113+
114+
**Pros**: Includes uncommitted changes
115+
116+
**Cons**:
117+
118+
- Copies local secrets and build artifacts
119+
- No version control guarantee
120+
- Inconsistent between development and production
121+
- Larger transfer size
122+
123+
### Option 2: Separate Config Management
124+
125+
```bash
126+
# Keep templates separate from code deployment
127+
scp infrastructure/config/environments/*.tpl vm:/path/
128+
```
129+
130+
**Pros**: Templates can be updated independently
131+
132+
**Cons**:
133+
134+
- More complex deployment process
135+
- Configuration and code can get out of sync
136+
- Additional deployment step to fail
137+
138+
## Current Choice: Git Archive
139+
140+
We chose to keep `git archive` because:
141+
142+
1. **Production Safety**: Ensures only committed code is deployed
143+
2. **Consistency**: Same process for development and production
144+
3. **Simplicity**: Single deployment artifact
145+
4. **Version Control**: Clear audit trail of what was deployed
146+
147+
The trade-off is that **developers must commit template changes before E2E testing**,
148+
but this is actually a good practice that ensures:
149+
150+
- Template changes are reviewed and tested
151+
- No accidental deployment of uncommitted changes
152+
- Clear history of configuration changes
153+
154+
## Troubleshooting
155+
156+
### E2E Tests Fail After Template Changes
157+
158+
1. **Check if changes are committed**:
159+
160+
```bash
161+
git status infrastructure/config/environments/
162+
```
163+
164+
2. **If uncommitted, commit them**:
165+
166+
```bash
167+
git add infrastructure/config/environments/
168+
git commit -m "update: configuration templates for testing"
169+
```
170+
171+
3. **Re-run tests**:
172+
173+
```bash
174+
make test-e2e
175+
```
176+
177+
### Configuration Not Updated After Deployment
178+
179+
1. **Verify the git archive contains your changes**:
180+
181+
```bash
182+
git archive HEAD -- infrastructure/config/environments/ | tar -tz
183+
```
184+
185+
2. **Check template processing on VM**:
186+
187+
```bash
188+
ssh torrust@$VM_IP 'cd torrust-tracker-demo && cat infrastructure/config/environments/local.env'
189+
```
190+
191+
3. **Verify generated configuration**:
192+
193+
```bash
194+
ssh torrust@$VM_IP 'cd torrust-tracker-demo && cat application/.env'
195+
```
196+
197+
## Security Notes
198+
199+
- **Never commit production secrets** - Use placeholder values in templates
200+
- **Review template changes** - Configuration changes can affect security
201+
- **Test thoroughly** - Configuration errors can break the entire application
202+
- **Backup production configs** - Before deploying configuration changes
203+
204+
## Related Documentation
205+
206+
- [Deployment Guide](../../../docs/guides/integration-testing-guide.md)
207+
- [Twelve-Factor App Methodology](../../../docs/guides/integration-testing-guide.md#twelve-factor-compliance)
208+
- [Configuration Management ADR](../../../docs/adr/004-configuration-approach-files-vs-environment-variables.md)

‎infrastructure/scripts/deploy-app.sh‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,66 @@ get_vm_ip() {
4646
echo "${vm_ip}"
4747
}
4848

49+
# Check git repository status and warn about uncommitted changes
50+
check_git_status() {
51+
log_info "Checking git repository status..."
52+
53+
cd "${PROJECT_ROOT}"
54+
55+
# Check if we're in a git repository
56+
if ! git rev-parse --git-dir >/dev/null 2>&1; then
57+
log_warning "Not in a git repository - deployment will use current directory state"
58+
return 0
59+
fi
60+
61+
# Check for uncommitted changes in configuration templates
62+
local config_changes
63+
config_changes=$(git status --porcelain infrastructure/config/environments/ 2>/dev/null || echo "")
64+
65+
if [[ -n "${config_changes}" ]]; then
66+
log_warning "==============================================="
67+
log_warning "⚠️ UNCOMMITTED CONFIGURATION CHANGES DETECTED"
68+
log_warning "==============================================="
69+
log_warning "The following configuration template files have uncommitted changes:"
70+
echo "${config_changes}" | while IFS= read -r line; do
71+
log_warning " ${line}"
72+
done
73+
log_warning ""
74+
log_warning "IMPORTANT: Deployment uses 'git archive' which only includes committed files."
75+
log_warning "Your uncommitted changes will NOT be deployed to the VM."
76+
log_warning ""
77+
log_warning "To include these changes in deployment:"
78+
log_warning " 1. git add infrastructure/config/environments/"
79+
log_warning " 2. git commit -m 'update: configuration templates'"
80+
log_warning " 3. Re-run deployment"
81+
log_warning ""
82+
log_warning "To continue without committing (deployment will use last committed version):"
83+
log_warning " Press ENTER to continue or Ctrl+C to abort"
84+
log_warning "==============================================="
85+
read -r
86+
fi
87+
88+
# Check for any other uncommitted changes (informational)
89+
local all_changes
90+
all_changes=$(git status --porcelain 2>/dev/null | wc -l)
91+
92+
if [[ "${all_changes}" -gt 0 ]]; then
93+
local git_status
94+
git_status=$(git status --short 2>/dev/null || echo "")
95+
log_info "Repository has ${all_changes} uncommitted changes (git archive will use committed version)"
96+
if [[ "${all_changes}" -le 10 ]]; then
97+
log_info "Uncommitted files:"
98+
echo "${git_status}" | while IFS= read -r line; do
99+
log_info " ${line}"
100+
done
101+
else
102+
log_info "Run 'git status' to see all uncommitted changes"
103+
fi
104+
else
105+
log_success "Repository working tree is clean - deployment will match current state"
106+
fi
107+
}
108+
49109
# Test SSH connectivity and wait for system readiness
50110
test_ssh_connection() {
51111
local vm_ip="$1"
@@ -542,6 +602,9 @@ main() {
542602
log_info "Starting application deployment (Twelve-Factor Release + Run Stages)"
543603
log_info "Environment: ${ENVIRONMENT}"
544604

605+
# Check git status and warn about uncommitted changes
606+
check_git_status
607+
545608
local vm_ip
546609
vm_ip=$(get_vm_ip)
547610

0 commit comments

Comments
 (0)