Torrust Tracker Demo

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.

🏗️ Repository Structure

This repository is organized into two main 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 testing 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

📚 docs/

Project documentation - Guides, security, and reference materials

• General project documentation
• Security and auditing information
• Cross-cutting concerns

Demo Tracker

• 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.

🚀 Quick Start

For detailed setup instructions, see the specific documentation:

• Infrastructure: Infrastructure Quick Start
• Application: Application README

Complete Development Setup

# 1. Setup infrastructure dependencies
make dev-setup
# Log out and log back in for group permissions

# 2. Configure SSH key
make setup-ssh-key
# Edit infrastructure/terraform/local.tfvars with your SSH public key

# 3. Deploy VM and application
make apply                                    # Deploy VM
make ssh                                     # Access VM
docker compose -f application/compose.yaml up -d  # Deploy application
make destroy                                 # Clean up

📚 Documentation

Infrastructure Documentation

• Infrastructure Quick Start - Get started in 5 minutes
• Complete Infrastructure Setup - Detailed guide
• Infrastructure Overview - Complete capabilities
• libvirt Troubleshooting - Fix common issues

Application Documentation

• Application Overview - Application components and deployment
• Production Setup - Production deployment with MySQL
• Deployment Guide - Deployment procedures
• Backup Procedures - Data backup and recovery
• Rollback Guide - Application rollbacks
• Useful Commands - Common operations
• Firewall Requirements - Network access requirements

General Documentation

• 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

🛠️ Development

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

Code Quality and Linting

The project uses automated linting to ensure code quality and consistency:

# Run all linting checks
make lint

# Run individual linters
make lint-yaml        # YAML files (yamllint)
make lint-shell       # Shell scripts (shellcheck)
make lint-markdown    # Markdown files (markdownlint)

Required tools:

• yamllint - YAML syntax and style checking
• shellcheck - Shell script analysis
• markdownlint - 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.