guides

User Guides Documentation

This directory contains comprehensive guides for deploying, configuring, and testing the Torrust Tracker Demo across different environments and use cases.

📁 Directory Structure

guides/
├── README.md                              # This file - guides overview
├── providers/                             # Provider-specific deployment guides
│   ├── README.md                          # Providers overview
│   └── hetzner/                           # Hetzner Cloud guides
│       ├── README.md                      # Hetzner integration overview
│       └── hetzner-cloud-setup-guide.md  # Hetzner Cloud server setup
├── deployment-guide.md                   # Complete deployment guide (consolidated)
├── dns-setup-for-testing.md              # DNS configuration for testing
├── grafana-setup-guide.md                # Grafana monitoring setup
├── grafana-subdomain-setup.md            # Grafana subdomain configuration
├── integration-testing-guide.md          # Full infrastructure testing
├── smoke-testing-guide.md                # Quick functionality validation
├── ssl-testing-guide.md                  # SSL certificate testing
└── database-backup-testing-guide.md      # Database backup procedures
├── mysql-password-url-encoding.md       # Safe credentials in DSNs (URL encoding)

🎯 Quick Navigation

🚀 Getting Started

Guide	Description	Time	Use Case
Deployment Guide	Complete deployment guide	30 min	First deployment
Integration Testing Guide	Complete testing setup	15 min	Development
Smoke Testing Guide	Quick validation	5 min	Post-deployment

☁️ Cloud Providers

Provider	Documentation	Status
Hetzner	Provider Guide	✅ Fully Supported
AWS	Coming Soon	🚧 Planned
DigitalOcean	Coming Soon	🚧 Planned
Vultr	Coming Soon	🚧 Planned

🔧 Configuration & Setup

Guide	Description	Complexity
DNS Setup for Testing	General DNS configuration	Beginner
Grafana Setup Guide	Monitoring dashboard setup	Intermediate
Grafana Subdomain Setup	Subdomain configuration	Intermediate
SSL Testing Guide	Certificate configuration	Advanced
MySQL DSN URL Encoding	Safe credentials in URLs/DSNs	Beginner

🧪 Testing & Validation

Guide	Description	Time	Scope
Integration Testing Guide	Full infrastructure test	10-15 min	Complete deployment
Smoke Testing Guide	Quick functionality check	3-5 min	Core features only
Database Backup Testing	Backup validation	5-10 min	Data persistence

🎨 Guide Categories

Deployment Guides

Purpose: Step-by-step instructions for deploying the Torrust Tracker Demo

• Cloud Deployment: General cloud deployment procedures
• Provider-Specific: Detailed guides for specific cloud providers
• Local Testing: Development environment setup

Configuration Guides

Purpose: Detailed configuration for specific components and features

• DNS Management: Domain and subdomain configuration
• SSL Certificates: HTTPS and certificate management
• Monitoring: Grafana and Prometheus setup
• Database: MySQL configuration and backups

Testing Guides

Purpose: Validation and testing procedures for different scenarios

• Integration Testing: Complete infrastructure validation
• Smoke Testing: Quick functional validation
• Component Testing: Specific service validation

🚀 Recommended Workflow

For New Users

1. Start Here: Deployment Guide
2. Choose Provider: Providers Directory
3. Validate: Smoke Testing Guide
4. Monitor: Grafana Setup Guide

For Developers

1. Local Setup: Integration Testing Guide
2. Provider Testing: Provider-Specific Guides
3. Component Validation: Individual Component Guides
4. Full Validation: Testing Guides

For Operators

1. Production Deployment: Provider Guides
2. Monitoring Setup: Grafana Guides
3. Backup Procedures: Database Backup Guide
4. SSL Management: SSL Testing Guide

📖 Contributing to Guides

Writing New Guides

When creating new guides:

1. Follow the structure: Use consistent formatting and sections
2. Include prerequisites: List required tools and setup
3. Provide examples: Include command examples and expected output
4. Add troubleshooting: Common issues and solutions
5. Test thoroughly: Validate all commands and procedures

Guide Template

# Guide Title

Brief description of what this guide covers and when to use it.

## Prerequisites

- Required tools and setup
- Previous guides or knowledge needed

## Step-by-Step Instructions

### Step 1: Clear Action Title

Description and commands...

### Step 2: Next Action

Description and commands...

## Validation

How to verify the guide worked correctly.

## Troubleshooting

Common issues and solutions.

## Related Documentation

Links to other relevant guides.

Provider-Specific Guides

For new cloud provider support:

1. Create provider directory: providers/{provider-name}/
2. Add provider README: Overview of provider integration
3. Create setup guides: Infrastructure and DNS setup
4. Update main documentation: Add to providers list
5. Test thoroughly: Validate with actual provider resources

🔗 External Resources

General Cloud Documentation

• The Twelve-Factor App - Application deployment methodology
• Infrastructure as Code Guide
• OpenTofu Documentation

Testing Resources

• Testing Strategies for Infrastructure
• End-to-End Testing Best Practices

This guide documentation provides comprehensive coverage for deploying and managing the Torrust Tracker Demo across different environments and use cases.