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

Commit 3471409

Browse files
committed
docs: [#26] add 12-factor deployment process overview
- Add comprehensive 4-step deployment process section to README.md - Enhance cloud deployment guide with detailed workflow explanation - Add ADR reference table to copilot instructions for contributor guidance - Clarify separation between infrastructure provisioning and application deployment - Document Build/Release/Run stages alignment with twelve-factor methodology
1 parent 49aa4f8 commit 3471409

File tree

3 files changed

+105
-0
lines changed

3 files changed

+105
-0
lines changed

.github/copilot-instructions.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,19 @@ torrust-tracker-demo/
182182
- **Cross-cutting**: Project-wide documentation and ADRs
183183
- **Architecture Decisions**: Documented design choices and rationale
184184

185+
#### Architecture Decision Records (ADRs)
186+
187+
Key design decisions are documented in `docs/adr/`. Contributors should review relevant ADRs when working on related features:
188+
189+
| ADR | Title | Description |
190+
|-----|-------|-------------|
191+
| [ADR-001](../docs/adr/001-makefile-location.md) | Makefile Location | Why the main Makefile is at repository root |
192+
| [ADR-002](../docs/adr/002-docker-for-all-services.md) | Docker for All Services | Why we use Docker for all services including UDP tracker |
193+
| [ADR-003](../docs/adr/003-use-mysql-over-mariadb.md) | Use MySQL Over MariaDB | Database backend selection rationale |
194+
| [ADR-004](../docs/adr/004-configuration-approach-files-vs-environment-variables.md) | Configuration Approach | Files vs environment variables for configuration |
195+
| [ADR-005](../docs/adr/005-sudo-cache-management-for-infrastructure-operations.md) | Sudo Cache Management | Managing sudo credentials during infrastructure operations |
196+
| [ADR-006](../docs/adr/006-ssl-certificate-generation-strategy.md) | SSL Certificate Generation Strategy | Approach for SSL certificate management |
197+
185198
## 🛠️ Development Workflow
186199

187200
### Quick Start for Contributors

README.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,51 @@ clear separation between infrastructure provisioning and application deployment:
9090
- **Environment-based Configuration**: Template system with `local.env.tpl` and `production.env.tpl`
9191
- **Build/Release/Run Stages**: Proper separation of configuration processing, deployment, and execution
9292

93+
## 🚀 Deployment Process Overview
94+
95+
This project follows a **four-step deployment process** based on twelve-factor app principles:
96+
97+
### 1. **Configure Environment Variables**
98+
99+
Customize deployment settings using environment-specific templates:
100+
101+
- `infrastructure/config/environments/local.env.tpl``local.env`
102+
- `infrastructure/config/environments/production.env.tpl``production.env`
103+
- Contains ALL deployment configuration (infrastructure, SSL, backups, application secrets)
104+
105+
### 2. **Provision Infrastructure**
106+
107+
Create and configure the target environment:
108+
109+
- **VM Creation**: Deploy virtual machine with specified resources
110+
- **System Setup**: cloud-init installs dependencies, configures firewall, sets up users
111+
- **Platform Preparation**: Ready environment for application deployment
112+
113+
### 3. **Deploy Application** (Build + Release + Run Stages)
114+
115+
Deploy the application stack following twelve-factor principles:
116+
117+
- **Build**: Prepare application artifacts and configuration files
118+
- **Release**: Generate SSL certificates, create Docker environment files, copy configs
119+
- **Run**: Start Docker Compose stack (tracker, MySQL, Nginx, Grafana, Prometheus)
120+
121+
### 4. **Validation**
122+
123+
Verify deployment health and functionality:
124+
125+
- Service health checks (HTTP/UDP endpoints)
126+
- Database connectivity validation
127+
- Monitoring dashboard accessibility
128+
- End-to-end smoke testing
129+
130+
### Quick Commands
131+
132+
```bash
133+
make infra-apply ENVIRONMENT=local # Steps 1-2: Configure + Provision
134+
make app-deploy ENVIRONMENT=local # Step 3: Deploy Application
135+
make app-health-check ENVIRONMENT=local # Step 4: Validation
136+
```
137+
93138
## Demo Tracker
94139

95140
- **HTTP Tracker**: <https://tracker.torrust-demo.com/announce>

docs/guides/cloud-deployment-guide.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,53 @@ and testing. Hetzner Cloud support is planned as the next implementation target.
1212
The process combines Infrastructure as Code with application deployment automation to
1313
provide a streamlined deployment experience, following twelve-factor app methodology.
1414

15+
## Deployment Process
16+
17+
This project implements a **four-step deployment workflow** aligned with twelve-factor app principles:
18+
19+
### Step 1: Configure Environment Variables
20+
21+
Create environment-specific configuration from templates:
22+
23+
- **Local Development**: `infrastructure/config/environments/local.env.tpl``local.env`
24+
- **Production**: `infrastructure/config/environments/production.env.tpl``production.env`
25+
26+
The environment file contains **all deployment configuration**, including:
27+
28+
- Infrastructure settings (VM specs, network configuration)
29+
- Application secrets (database passwords, API tokens)
30+
- SSL certificate configuration (domains, email for Let's Encrypt)
31+
- Backup and monitoring settings
32+
33+
### Step 2: Provision Infrastructure
34+
35+
Deploy and configure the target environment:
36+
37+
- **VM Creation**: Deploy virtual machine with specified resources
38+
- **System Dependencies**: cloud-init installs Docker, configures firewall, creates users
39+
- **Network Setup**: Configure firewall rules, SSH access, system security
40+
- **Platform Readiness**: Environment prepared for application deployment
41+
42+
### Step 3: Deploy Application (Build + Release + Run)
43+
44+
Deploy the application stack following twelve-factor methodology:
45+
46+
- **Build Stage**: Prepare application artifacts and configuration templates
47+
- **Release Stage**:
48+
- Generate SSL certificates (Let's Encrypt or self-signed)
49+
- Create Docker environment files from templates
50+
- Copy application configurations to target VM
51+
- **Run Stage**: Start Docker Compose stack (Torrust Tracker, MySQL, Nginx, Grafana, Prometheus)
52+
53+
### Step 4: Validation
54+
55+
Verify deployment health and functionality:
56+
57+
- **Service Health**: HTTP/UDP endpoint availability checks
58+
- **Database Connectivity**: MySQL connection and schema validation
59+
- **Monitoring Access**: Grafana dashboard accessibility
60+
- **End-to-end Testing**: Tracker announce/scrape functionality
61+
1562
## Prerequisites
1663

1764
### Local Requirements

0 commit comments

Comments
 (0)