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

dns-setup-for-testing.md

Latest commit

 

History

History
357 lines (252 loc) · 10.2 KB

dns-setup-for-testing.md

File metadata and controls

357 lines (252 loc) · 10.2 KB

DNS Setup Guide for Domain-Based Testing

This guide explains how to configure DNS to use your domain for manual testing of the Torrust Tracker with real URLs instead of IP addresses.

🎯 Overview

When you deploy to Hetzner Cloud, you get an IP address (e.g., 138.199.166.49), but for proper testing you want to use your configured domain (e.g., tracker.staging-torrust-demo.com) to:

  • Test REST API endpoints with proper URLs
  • Perform UDP/HTTP tracker announces with domain names
  • Access web interfaces (Grafana) with friendly URLs
  • Validate SSL certificate functionality

Subdomain Architecture

The infrastructure implements a professional subdomain-based architecture with separate domains for different services:

  • tracker.yourdomain.com - Main tracker API and HTTP tracker endpoints
  • grafana.yourdomain.com - Grafana monitoring dashboard

This provides proper service isolation and follows professional deployment patterns. nginx acts as a reverse proxy routing traffic to the appropriate containerized services based on the subdomain.

🌐 DNS Configuration Methods

Method 1: Real DNS Setup (Recommended)

If you control the domain, set up proper DNS records:

Step 1: Get Your Server IP

# Get the current server IP from Terraform
cd infrastructure/terraform
tofu output vm_ip

# Or check from your environment
grep TRACKER_DOMAIN infrastructure/config/environments/production-hetzner.env

Step 2: Create DNS A Records

Access your DNS provider (cdmon.com, Cloudflare, Route53, etc.) and create:

# Main tracker subdomain
Type: A
Name: tracker
Value: <your_server_ip>
TTL: 300 (5 minutes for testing)

# Grafana monitoring subdomain (recommended)
Type: A
Name: grafana
Value: <your_server_ip>
TTL: 300 (5 minutes for testing)

Step 3: Verify DNS Propagation

# Test DNS resolution for both subdomains
nslookup tracker.staging-torrust-demo.com
nslookup grafana.staging-torrust-demo.com
dig tracker.staging-torrust-demo.com
dig grafana.staging-torrust-demo.com

# Test connectivity
ping tracker.staging-torrust-demo.com
ping grafana.staging-torrust-demo.com

Method 2: Local DNS Override (Quick Testing)

For immediate testing without DNS changes:

# Get your server IP
SERVER_IP=$(cd infrastructure/terraform && tofu output -raw vm_ip)

# Add to /etc/hosts
echo "$SERVER_IP tracker.staging-torrust-demo.com" | sudo tee -a /etc/hosts
echo "$SERVER_IP grafana.staging-torrust-demo.com" | sudo tee -a /etc/hosts

# Verify the entries
grep staging-torrust-demo.com /etc/hosts

# Test resolution
ping tracker.staging-torrust-demo.com
ping grafana.staging-torrust-demo.com

Note: This only affects your local machine. Other users won't be able to access the domain.

🧪 Manual Testing Examples

1. REST API Testing

Once DNS is configured, test API endpoints:

# Health check
curl -s https://tracker.staging-torrust-demo.com/api/health_check | jq

# Get admin token from server
ADMIN_TOKEN=$(ssh torrust@tracker.staging-torrust-demo.com \
  "grep TRACKER_ADMIN_TOKEN /var/lib/torrust/compose/.env | cut -d'=' -f2 | tr -d '\"'")

# Statistics endpoint
curl -s "https://tracker.staging-torrust-demo.com/api/v1/stats?token=$ADMIN_TOKEN" | jq

# Metrics endpoint (Prometheus format)
curl -s https://tracker.staging-torrust-demo.com/metrics | head -20

2. UDP Tracker Testing

Use the Torrust Tracker client tools with your domain:

# Clone tracker repository for client tools
git clone https://github.com/torrust/torrust-tracker
cd torrust-tracker

# Test UDP tracker port 6868
cargo run -p torrust-tracker-client --bin udp_tracker_client announce \
  udp://tracker.staging-torrust-demo.com:6868/announce \
  9c38422213e30bff212b30c360d26f9a02136422 | jq

# Test UDP tracker port 6969
cargo run -p torrust-tracker-client --bin udp_tracker_client announce \
  udp://tracker.staging-torrust-demo.com:6969/announce \
  9c38422213e30bff212b30c360d26f9a02136422 | jq

3. HTTP Tracker Testing

# Test HTTP tracker through nginx proxy
cargo run -p torrust-tracker-client --bin http_tracker_client announce \
  https://tracker.staging-torrust-demo.com \
  9c38422213e30bff212b30c360d26f9a02136422 | jq

# Test HTTP tracker scrape
cargo run -p torrust-tracker-client --bin http_tracker_client scrape \
  https://tracker.staging-torrust-demo.com \
  9c38422213e30bff212b30c360d26f9a02136422 | jq

4. Web Interface Access

# Get Grafana credentials
ssh torrust@tracker.staging-torrust-demo.com \
  "grep GF_SECURITY_ADMIN /var/lib/torrust/compose/.env"

# Access Grafana with subdomain (requires nginx configuration)
open https://grafana.staging-torrust-demo.com

# Alternative: Access via port (current setup)
open https://tracker.staging-torrust-demo.com:3000

🔒 SSL Certificate Handling

Current Setup: Self-Signed Certificates

Your deployment uses self-signed certificates, which means:

  • ✅ HTTPS encryption works
  • ⚠️ Browsers show security warnings
  • ⚠️ Need to bypass certificate verification for testing

Testing with Self-Signed Certificates

# Bypass certificate verification
curl -k -s https://tracker.staging-torrust-demo.com/api/health_check | jq

# Accept certificate in browser:
# Chrome: "Advanced" → "Proceed to tracker.staging-torrust-demo.com (unsafe)"
# Firefox: "Advanced" → "Accept the Risk and Continue"

Upgrade to Let's Encrypt (Optional)

For real SSL certificates, you can implement Let's Encrypt automation:

# Example: Add Let's Encrypt support
# This would require implementing certbot automation in the deployment scripts
# Currently not automated - manual setup required

🎯 Complete Testing Workflow

Here's a complete testing workflow using your domain:

Step 1: Verify DNS and Connectivity

# Test DNS resolution
nslookup tracker.staging-torrust-demo.com

# Test basic connectivity
curl -k -I https://tracker.staging-torrust-demo.com

Step 2: Test All Endpoints

# Health check
curl -k -s https://tracker.staging-torrust-demo.com/api/health_check

# Get admin token
ADMIN_TOKEN=$(ssh torrust@tracker.staging-torrust-demo.com \
  "grep TRACKER_ADMIN_TOKEN /var/lib/torrust/compose/.env | cut -d'=' -f2 | tr -d '\"'")

# Statistics
curl -k -s "https://tracker.staging-torrust-demo.com/api/v1/stats?token=$ADMIN_TOKEN"

# Test UDP tracker
cd torrust-tracker
cargo run -p torrust-tracker-client --bin udp_tracker_client announce \
  udp://tracker.staging-torrust-demo.com:6868/announce \
  9c38422213e30bff212b30c360d26f9a02136422

# Test HTTP tracker
cargo run -p torrust-tracker-client --bin http_tracker_client announce \
  https://tracker.staging-torrust-demo.com \
  9c38422213e30bff212b30c360d26f9a02136422

Step 3: Monitor and Debug

# Check service status
ssh torrust@tracker.staging-torrust-demo.com \
  "cd /home/torrust/github/torrust/torrust-tracker-demo/application && \
   docker compose --env-file /var/lib/torrust/compose/.env ps"

# Check logs
ssh torrust@tracker.staging-torrust-demo.com \
  "cd /home/torrust/github/torrust/torrust-tracker-demo/application && \
   docker compose --env-file /var/lib/torrust/compose/.env logs tracker"

# Access Grafana for monitoring
open https://tracker.staging-torrust-demo.com:3000

🔧 Troubleshooting

DNS Issues

# Check if DNS is working
dig tracker.staging-torrust-demo.com
nslookup tracker.staging-torrust-demo.com

# Clear DNS cache (if needed)
sudo systemctl flush-dns  # Linux
sudo dscacheutil -flushcache  # macOS

Certificate Issues

# Test certificate details
openssl s_client -connect tracker.staging-torrust-demo.com:443 -servername tracker.staging-torrust-demo.com

# Check certificate on server
ssh torrust@tracker.staging-torrust-demo.com \
  "openssl x509 -in /var/lib/torrust/proxy/certs/server.crt -text -noout"

Service Issues

# Check if services are running
ssh torrust@tracker.staging-torrust-demo.com \
  "cd /home/torrust/github/torrust/torrust-tracker-demo/application && \
   docker compose --env-file /var/lib/torrust/compose/.env ps"

# Check firewall rules
ssh torrust@tracker.staging-torrust-demo.com "sudo ufw status verbose"

# Test ports directly
nc -zv tracker.staging-torrust-demo.com 6868  # UDP tracker
nc -zv tracker.staging-torrust-demo.com 6969  # UDP tracker
nc -zv tracker.staging-torrust-demo.com 7070  # HTTP tracker
nc -zv tracker.staging-torrust-demo.com 1212  # API port
nc -zv tracker.staging-torrust-demo.com 3000  # Grafana

📋 Quick Reference

Essential URLs

  • Health Check: https://tracker.staging-torrust-demo.com/api/health_check
  • Statistics: https://tracker.staging-torrust-demo.com/api/v1/stats?token=TOKEN
  • Metrics: https://tracker.staging-torrust-demo.com/metrics
  • Grafana: https://grafana.staging-torrust-demo.com (subdomain configured)

UDP Tracker URLs

  • Port 6868: udp://tracker.staging-torrust-demo.com:6868/announce
  • Port 6969: udp://tracker.staging-torrust-demo.com:6969/announce

📊 Accessing Grafana Dashboard

The Grafana monitoring dashboard is available at the dedicated subdomain:

Access URL

# Open Grafana in your browser
https://grafana.staging-torrust-demo.com

Default Credentials

  • Username: admin
  • Password: Check your .env file for GF_SECURITY_ADMIN_PASSWORD

Browser Certificate Warning

Since the deployment uses self-signed certificates, your browser will show a security warning. This is expected for testing environments.

To proceed:

  1. Click "Advanced" or "Show Details"
  2. Click "Proceed to grafana.staging-torrust-demo.com (unsafe)" or equivalent
  3. Accept the certificate for the current session

Grafana Features

  • Torrust Tracker Metrics: Pre-configured dashboards for tracker performance
  • System Monitoring: Server resource usage and health metrics
  • Real-time Updates: Live data from Prometheus scraping
  • Historical Data: Trend analysis and performance over time

HTTP Tracker URLs

  • Announce: https://tracker.staging-torrust-demo.com/announce
  • Scrape: https://tracker.staging-torrust-demo.com/scrape

Common Test Infohash

  • Test Hash: 9c38422213e30bff212b30c360d26f9a02136422

This completes the DNS setup guide for domain-based testing of your Torrust Tracker deployment!