This repo contains all the configuration needed to run the live Torrust Tracker demo.
It's also used to track issues in production.
IMPORTANT: We are in the process of splitting the Torrust Demo repo into two repos. This will allow us to deploy both services independently and it would make easier for users who only want to setup the tracker to re-use this setup. The content of this repo may change drastically in the future.
This repository is organized into distinct concerns:
π¦ infrastructure/
Server and system setup - VMs, networking, operating system configuration
- OpenTofu/Terraform for VM provisioning
- cloud-init templates for system setup
- libvirt/KVM for local testing
- Infrastructure unit tests and validation
π application/
Application deployment and configuration - Docker services, app config
- Docker Compose for service orchestration
- Torrust Tracker configuration
- Nginx, Prometheus, Grafana setup
- Application scripts and utilities
π§ͺ tests/
End-to-end testing - Complete system validation
- E2E deployment workflow tests
- Integration testing automation
- System-wide validation
π docs/
Project documentation - Guides, security, and reference materials
- General project documentation
- Security and auditing information
- Cross-cutting concerns
This project implements a complete twelve-factor app architecture with clear separation between infrastructure provisioning and application deployment:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Configuration Management β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β’ Environment Templates (local.env.tpl, production.env.tpl) β
β β’ Configuration Processing (configure-env.sh) β
β β’ Template Rendering (.tpl β actual configs) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Infrastructure Layer β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β’ VM Provisioning (provision-infrastructure.sh) β
β β’ Environment-specific Setup (templated cloud-init) β
β β’ Provider Abstraction (local implemented, cloud planned) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Application Layer β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β’ Environment-aware Deployment (templated configs) β
β β’ Dynamic Service Configuration β
β β’ Comprehensive Health Validation β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
- Complete Twelve-Factor Compliance: All 12 factors implemented
- Infrastructure/Application Separation: Clean separation with
make infra-apply
andmake app-deploy
- Environment-based Configuration: Template system with
local.env.tpl
andproduction.env.tpl
- Build/Release/Run Stages: Proper separation of configuration processing, deployment, and execution
This project follows a four-step deployment process based on twelve-factor app principles:
Customize deployment settings using environment-specific templates:
infrastructure/config/environments/local.env.tpl
βlocal.env
infrastructure/config/environments/production.env.tpl
βproduction.env
- Contains ALL deployment configuration (infrastructure, SSL, backups, application secrets)
Create and configure the target environment:
- VM Creation: Deploy virtual machine with specified resources
- System Setup: cloud-init installs dependencies, configures firewall, sets up users
- Platform Preparation: Ready environment for application deployment
Deploy the application stack following twelve-factor principles:
- Build: Prepare application artifacts and configuration files
- Release: Generate SSL certificates, create Docker environment files, copy configs
- Run: Start Docker Compose stack (tracker, MySQL, Nginx, Grafana, Prometheus)
Verify deployment health and functionality:
- Service health checks (HTTP/UDP endpoints)
- Database connectivity validation
- Monitoring dashboard accessibility
- End-to-end smoke testing
make infra-apply ENVIRONMENT=local # Steps 1-2: Configure + Provision
make app-deploy ENVIRONMENT=local # Step 3: Deploy Application
make app-health-check ENVIRONMENT=local # Step 4: Validation
- HTTP Tracker: https://tracker.torrust-demo.com/announce
- UDP Tracker: udp://tracker.torrust-demo.com:6969/announce
For detailed information about all tracker ports and their specific purposes, see Application Port Documentation.
The demo includes monitoring with Grafana dashboards for performance metrics, peer connections, and system health.
New users start here: Deployment Guide - Complete guide for deploying Torrust Tracker locally or in the cloud
For detailed setup instructions, see the specific documentation:
- Infrastructure: Infrastructure Quick Start
- Application: Application README
# 1. Setup infrastructure dependencies
make dev-setup
# Log out and log back in for group permissions
# 2. Configure local environment
make infra-config-local
# Edit infrastructure/terraform/local.tfvars with your SSH public key
# 3. Deploy infrastructure and application (twelve-factor workflow)
make infra-apply ENVIRONMENT=local # Deploy VM (infrastructure only)
make app-deploy ENVIRONMENT=local # Deploy application (Build + Release + Run)
make app-health-check ENVIRONMENT=local # Validate deployment
# 4. Access VM and check status
make vm-ssh # Access VM
make infra-destroy ENVIRONMENT=local # Clean up
# Alternative: Complete workflow in one command
make dev-deploy ENVIRONMENT=local # Does all steps 3-4
- Infrastructure Quick Start - Get started in 5 minutes
- Complete Infrastructure Setup - Detailed guide
- Infrastructure Overview - Complete capabilities
- libvirt Troubleshooting - Fix common issues
- Application Overview - Application components and deployment
- Production Setup - Production deployment with MySQL
- Application Deployment Procedures - Detailed application deployment procedures
- Backup Procedures - Data backup and recovery
- Rollback Guide - Application rollbacks
- Useful Commands - Common operations
- Firewall Requirements - Network access requirements
- Deployment Guide - Main deployment guide for local development and planned cloud deployment
- Documentation Structure - Cross-cutting documentation
- Architecture Decisions - Design decisions and rationale
- ADR-001: Makefile Location - Why the main Makefile is at repository root
- ADR-002: Docker for All Services - Why we use Docker for all services including UDP tracker
- ADR-003: Use MySQL Over MariaDB - Why we chose MySQL instead of MariaDB for the database backend
For contributors and developers:
- Infrastructure development: See
infrastructure/README.md
- Application development: See
application/README.md
- General contributing guidelines: See
.github/copilot-instructions.md
- Architecture decisions: See
docs/adr/
for design rationale
The project uses automated linting to ensure code quality and consistency:
# Run all linting checks
make lint
# Run individual linters (use script directly)
./scripts/lint.sh --yaml # YAML files (yamllint)
./scripts/lint.sh --shell # Shell scripts (shellcheck)
./scripts/lint.sh --markdown # Markdown files (markdownlint)
Required tools:
yamllint
- YAML syntax and style checkingshellcheck
- Shell script analysismarkdownlint
- Markdown style and structure checking
Installation:
# Ubuntu/Debian
sudo apt-get install yamllint shellcheck
sudo npm install -g markdownlint-cli
# Or install all project dependencies
make install-deps
Linting is automatically run in CI/CD pipelines to validate all contributions.
Note: The main
Makefile
is kept at the root level to serve as the project's primary interface. See ADR-001 for the full rationale.