Skip to content

Commit a0456e8

Browse files
josecelanojosecelano
committed
refactor: [#14] align integration tests with 12-factor configuration approach
- Refactored setup_torrust_tracker function to use git archive for clean file copying - Updated installation script to require .env file (12-factor principle) - Removed fallback to .env.production in favor of infrastructure-generated configs - Added proper error handling and validation in installation process - Updated integration testing guide to reflect new workflow - Added deprecation notice to .env.production file - Created refactoring documentation with migration notes This change ensures integration tests use the same configuration approach as production deployments and follows 12-factor principles strictly.
1 parent 00e13bf commit a0456e8

File tree

6 files changed

+331
-45
lines changed

6 files changed

+331
-45
lines changed

‎application/.env.production

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# Torrust Tracker Demo - Production Environment Configuration
22
#
3+
# DEPRECATED: This file is deprecated in favor of the new 12-factor configuration approach.
4+
# Use the infrastructure configuration system instead:
5+
# make configure-production # Generate production configuration
6+
# make configure-local # Generate local development configuration
7+
#
38
# This configuration uses MySQL as the default database backend.
49
# Make sure to change the default passwords before deployment!
510
#

‎application/share/bin/install.sh

Lines changed: 40 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,22 @@
11
#!/bin/bash
22

3+
# Torrust Tracker Demo Installation Script
4+
# This script creates the required directory structure for the application.
5+
# Following 12-factor principles, it expects .env to be provided by the infrastructure layer.
6+
37
if ! [ -f "./.env" ]; then
4-
echo "Creating compose .env './.env'"
5-
cp .env.production .env
8+
echo "ERROR: Environment file './.env' not found!"
9+
echo "The .env file must be provided by the infrastructure configuration system."
10+
echo "Expected location: $(pwd)/.env"
11+
echo ""
12+
echo "To generate the .env file, run:"
13+
echo " make configure-local # For local development"
14+
echo " make configure-production # For production deployment"
15+
exit 1
616
fi
717

18+
echo "Found environment file: ./.env"
19+
820
## Proxy
921

1022
mkdir -p ./storage/proxy/etc/nginx-conf
@@ -33,16 +45,37 @@ fi
3345

3446
mkdir -p ./storage/tracker/etc
3547

36-
if ! [ -f "./storage/tracker/etc/tracker.prod.container.sqlite3.toml" ]; then
37-
echo "Creating tracker configuration: './storage/tracker/etc/tracker.toml'"
38-
cp ./share/container/default/config/tracker.prod.container.sqlite3.toml ./storage/tracker/etc/tracker.toml
48+
# Verify tracker configuration exists (should be provided by infrastructure)
49+
if ! [ -f "./storage/tracker/etc/tracker.toml" ]; then
50+
echo "ERROR: Tracker configuration file './storage/tracker/etc/tracker.toml' not found!"
51+
echo "This file should be generated by the infrastructure configuration system."
52+
echo "Expected location: $(pwd)/storage/tracker/etc/tracker.toml"
53+
echo ""
54+
echo "To generate the configuration file, run:"
55+
echo " make configure-local # For local development"
56+
echo " make configure-production # For production deployment"
57+
exit 1
3958
fi
4059

60+
echo "Found tracker configuration: ./storage/tracker/etc/tracker.toml"
61+
4162
## Prometheus
4263

4364
mkdir -p ./storage/prometheus/etc
4465

66+
# Verify prometheus configuration exists (should be provided by infrastructure)
4567
if ! [ -f "./storage/prometheus/etc/prometheus.yml" ]; then
46-
echo "Creating prometheus config file: './storage/prometheus/etc/prometheus.yml'"
47-
cp ./share/container/default/config/prometheus.yml ./storage/prometheus/etc/prometheus.yml
68+
echo "ERROR: Prometheus configuration file './storage/prometheus/etc/prometheus.yml' not found!"
69+
echo "This file should be generated by the infrastructure configuration system."
70+
echo "Expected location: $(pwd)/storage/prometheus/etc/prometheus.yml"
71+
echo ""
72+
echo "To generate the configuration file, run:"
73+
echo " make configure-local # For local development"
74+
echo " make configure-production # For production deployment"
75+
exit 1
4876
fi
77+
78+
echo "Found prometheus configuration: ./storage/prometheus/etc/prometheus.yml"
79+
80+
echo "Installation completed successfully!"
81+
echo "All required directories created and configuration files verified."

‎docs/README.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,16 @@ This directory currently contains cross-cutting documentation:
3737
- [Phase 1: MySQL Migration](issues/12-use-mysql-instead-of-sqlite-by-default.md) -
3838
Detailed implementation plan for database migration from SQLite to MySQL
3939

40+
### 🔧 [`refactoring/`](refactoring/) (Refactoring Documentation)
41+
42+
**Major refactoring initiatives and changes** - Documentation of significant
43+
codebase changes, architectural improvements, and migration summaries.
44+
45+
**Current Refactoring Documentation:**
46+
47+
- [Integration Test Refactor Summary](refactoring/integration-test-refactor-summary.md) -
48+
Summary of changes made to align integration testing with 12-factor configuration principles
49+
4050
### Future Categories
4151

4252
The following directories can be created as needed:

‎docs/guides/integration-testing-guide.md

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -273,9 +273,15 @@ time make configure-local
273273
- Environment values applied to templates
274274
- **Time**: ~2 seconds
275275

276-
**What This Creates**: Final configuration files in `infrastructure/cloud-init/`
277-
from templates in `infrastructure/config/templates/` using values from
278-
`infrastructure/config/environments/local.env`.
276+
**What This Creates**: Final configuration files including:
277+
278+
- `application/.env` - Docker Compose environment file
279+
- `application/storage/tracker/etc/tracker.toml` - Tracker configuration
280+
- `application/storage/prometheus/etc/prometheus.yml` - Prometheus configuration
281+
- `infrastructure/cloud-init/` - VM provisioning files
282+
283+
These files are generated from templates in `infrastructure/config/templates/` using
284+
values from `infrastructure/config/environments/local.env`.
279285

280286
### 1.7.2 Validate Generated Configuration
281287

‎docs/refactoring/integration-test-refactor-summary.md

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# Integration Test Refactor Summary
2+
3+
> **Note**: This document describes interim changes made during the 12-factor refactoring process.
4+
> It should be removed once the refactoring described in `infrastructure/docs/refactoring/twelve-factor-refactor/`
5+
> is completed.
6+
7+
## Overview
8+
9+
This document summarizes the changes made to align the integration testing workflow with the 12-factor
10+
configuration principles currently being implemented in the Torrust Tracker Demo project.
11+
12+
## Changes Made
13+
14+
### 1. Updated `setup_torrust_tracker` Function (infrastructure/tests/test-integration.sh)
15+
16+
**Previous Approach:**
17+
18+
- Used `rsync` to copy the entire local repository with exclusions
19+
- Fallback to `.env.production` if `.env` was missing
20+
- Ad-hoc configuration handling
21+
22+
**New Approach:**
23+
24+
- Uses `git archive` to export only git-tracked files (equivalent to cloning but with current working
25+
version)
26+
- Runs `make configure-local` to generate configuration files using the new infrastructure system
27+
- Executes the official `application/share/bin/install.sh` script locally
28+
- Copies the properly configured `storage/` folder to the VM
29+
- Verifies critical configuration files exist on the VM
30+
31+
**Benefits:**
32+
33+
- Tests the exact version being developed (without untracked files)
34+
- Uses the official installation process instead of custom logic
35+
- Leverages the new 12-factor configuration system
36+
- More robust and maintainable
37+
38+
### 2. Updated Installation Script (application/share/bin/install.sh)
39+
40+
**Previous Approach:**
41+
42+
- Created `.env` from `.env.production` if missing
43+
- Copied configuration files from default templates
44+
45+
**New Approach:**
46+
47+
- Fails if `.env` is not present (12-factor principle)
48+
- Expects configuration files to be pre-generated by infrastructure system
49+
- Verifies that required configuration files exist
50+
- Provides helpful error messages pointing to the infrastructure commands
51+
52+
**Benefits:**
53+
54+
- Follows 12-factor principles strictly
55+
- No more arbitrary copying of default configurations
56+
- Clear error messages guide users to the correct configuration process
57+
- Separation of concerns between infrastructure and application layers
58+
59+
### 3. Updated Documentation
60+
61+
**Changes:**
62+
63+
- Added deprecation notice to `.env.production` file
64+
- Updated integration testing guide to reflect new workflow
65+
- Improved documentation of what files are generated by `make configure-local`
66+
67+
## Workflow Changes
68+
69+
### Before (Old Workflow)
70+
71+
```bash
72+
# Deploy VM
73+
make apply
74+
75+
# Copy repo with rsync and fallback configs
76+
setup_torrust_tracker() # Custom logic in test script
77+
78+
# Start services
79+
docker compose up -d
80+
```
81+
82+
### After (New Workflow)
83+
84+
```bash
85+
# Deploy VM
86+
make apply
87+
88+
# Generate configuration files locally
89+
make configure-local
90+
91+
# Use git archive to copy only tracked files
92+
git archive HEAD | extract to VM
93+
94+
# Run official installation script locally
95+
./application/share/bin/install.sh
96+
97+
# Copy configured storage folder to VM
98+
rsync storage/ to VM
99+
100+
# Start services
101+
docker compose up -d
102+
```
103+
104+
## Files Modified
105+
106+
1. **infrastructure/tests/test-integration.sh**
107+
- Refactored `setup_torrust_tracker` function
108+
- Improved error handling and logging
109+
- Added proper configuration verification
110+
111+
2. **application/share/bin/install.sh**
112+
- Now requires `.env` to be present (12-factor principle)
113+
- Verifies configuration files exist
114+
- Provides helpful error messages
115+
116+
3. **application/.env.production**
117+
- Added deprecation notice
118+
- Updated documentation to point to new configuration system
119+
120+
4. **docs/guides/integration-testing-guide.md**
121+
- Updated to reflect new configuration file generation
122+
123+
## Migration Notes
124+
125+
### For Developers
126+
127+
- The integration test now uses the official installation process
128+
- Configuration files are generated by the infrastructure system
129+
- The test workflow is more aligned with production deployment
130+
131+
### For Operations
132+
133+
- The installation script now fails fast if configuration is missing
134+
- Clear error messages guide to the correct configuration commands
135+
- No more implicit fallbacks to default configurations
136+
137+
## Testing
138+
139+
All changes have been validated with:
140+
141+
- ✅ Shell script linting (ShellCheck)
142+
- ✅ Markdown linting (markdownlint)
143+
- ✅ YAML linting (yamllint)
144+
- ✅ Full linting pipeline passes
145+
146+
## Next Steps
147+
148+
1. Test the updated integration workflow with `make test`
149+
2. Update any remaining documentation references to `.env.production`
150+
3. Consider removing `.env.production` once migration is complete
151+
4. Update production deployment guides to use the new configuration system
152+
153+
## Benefits Achieved
154+
155+
- **Consistency**: Integration tests now use the same configuration approach as production
156+
- **Maintainability**: Removed custom configuration logic from test scripts
157+
- **Robustness**: Proper error handling and validation
158+
- **12-Factor Compliance**: Configuration is externalized and validated
159+
- **Developer Experience**: Clear error messages and guidance
160+
- **Testing Fidelity**: Tests exactly what's being developed (git-tracked files only)

0 commit comments

Comments
 (0)