hetzner

Hetzner Provider Documentation

This directory contains guides for deploying the Torrust Tracker Demo using Hetzner services, including Hetzner Cloud for infrastructure and Hetzner DNS for domain management.

🏗️ Hetzner Services Integration

The Torrust Tracker Demo uses a comprehensive Hetzner setup:

┌─────────────────────────────────────────────────────────────────┐
│                     Hetzner Cloud                               │
│  ┌─────────────────┐    ┌─────────────────┐                     │
│  │   VM Instance   │    │   Networking    │                     │
│  │                 │    │                 │                     │
│  │ • Ubuntu 24.04  │    │ • Public IP     │                     │
│  │ • Docker Stack  │    │ • Firewall      │                     │
│  │ • Torrust App   │    │ • SSH Access    │                     │
│  └─────────────────┘    └─────────────────┘                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼ (A records)
┌─────────────────────────────────────────────────────────────────┐
│                      Hetzner DNS                                │
│  ┌─────────────────┐    ┌─────────────────┐                     │
│  │   DNS Zones     │    │   API Control   │                     │
│  │                 │    │                 │                     │
│  │ • torrust.dev   │    │ • Automated     │                     │
│  │ • Subdomains    │    │ • REST API      │                     │
│  │ • A Records     │    │ • CLI Tools     │                     │
│  └─────────────────┘    └─────────────────┘                     │
└─────────────────────────────────────────────────────────────────┘

📚 Available Guides

Setup and Configuration

Guide	Description	Use Case
Hetzner Cloud Setup Guide	Complete Hetzner Cloud server setup	Infrastructure provisioning

Note: DNS configuration is covered in the comprehensive Deployment Guide - Part 3: DNS Configuration.

Key Features

Hetzner Cloud Integration:

• Infrastructure as Code with OpenTofu/Terraform
• Automated VM provisioning with cloud-init
• Secure API token management
• Cost-effective server instances
• European data centers (GDPR compliant)

Hetzner DNS Integration:

• Full DNS automation via REST API
• Subdomain management (tracker., grafana.)
• Low TTL for quick updates
• Free DNS hosting
• Integration with any domain registrar

🚀 Quick Start

1. Prerequisites

• Hetzner account with Cloud and DNS access
• Domain registered at any provider (cdmon.com, Namecheap, etc.)
• Local development environment with OpenTofu/Terraform

2. API Token Setup

# Copy provider configuration template
cp infrastructure/config/templates/providers/hetzner.env.tpl infrastructure/config/providers/hetzner.env

# Edit the configuration file to add your tokens
# Add these lines to infrastructure/config/providers/hetzner.env:
#   HETZNER_API_TOKEN=your_64_character_cloud_api_token_here
#   HETZNER_DNS_API_TOKEN=your_dns_api_token_here

# Get your tokens from:
# Cloud API: https://console.hetzner.cloud/ → Project → Security → API Tokens
# DNS API: https://dns.hetzner.com/ → API Tokens

3. Domain Configuration

# Configure environment for Hetzner
cp infrastructure/config/environments/production-hetzner.env.tpl \
   infrastructure/config/environments/production-hetzner.env

# Edit configuration with your domain and settings
vim infrastructure/config/environments/production-hetzner.env

4. Deploy Infrastructure

# Provision Hetzner Cloud server
ENVIRONMENT=production-hetzner PROVIDER=hetzner make infra-apply

# Deploy application stack
ENVIRONMENT=production-hetzner PROVIDER=hetzner make app-deploy

# Validate deployment
ENVIRONMENT=production-hetzner PROVIDER=hetzner make app-health-check

🔧 Management Operations

Infrastructure Management

# View server status
ENVIRONMENT=production-hetzner PROVIDER=hetzner make infra-status

# Scale server resources (edit terraform.tfvars)
ENVIRONMENT=production-hetzner PROVIDER=hetzner make infra-plan
ENVIRONMENT=production-hetzner PROVIDER=hetzner make infra-apply

# Destroy infrastructure
ENVIRONMENT=production-hetzner PROVIDER=hetzner make infra-destroy

DNS Management

# View DNS records
./scripts/manage-hetzner-dns.sh list-records

# Update DNS records (after IP change)
./scripts/manage-hetzner-dns.sh update-records NEW_IP_ADDRESS

# Add new subdomain
./scripts/manage-hetzner-dns.sh create-record subdomain A IP_ADDRESS

💰 Cost Optimization

Hetzner Cloud Pricing (as of 2025)

Recommended Instance Types:

Instance	vCPU	RAM	Disk	Price/Month	Use Case
CX22	2	4GB	40GB	€5.83	Development/Testing
CX32	4	8GB	80GB	€11.66	Production (Small)
CX42	8	16GB	160GB	€23.33	Production (Medium)

Additional Costs:

• Hetzner DNS: Free for all domains
• Public IPv4: €1.19/month (included in server)
• Backups: 20% of server cost (optional)
• Load Balancer: €5.83/month (if needed)

Cost Optimization Tips

1. Right-size instances: Start with CX22, scale as needed
2. Use snapshots: For backup instead of continuous backup
3. Monitor usage: Use Grafana dashboards to track resource usage
4. Auto-scaling: Implement scripts for traffic-based scaling

🔍 Troubleshooting

Common Issues

Infrastructure Problems:

• API Token Issues: Verify tokens are configured correctly in infrastructure/config/providers/hetzner.env
• Network Connectivity: Check Hetzner status page for outages
• Resource Limits: Verify account limits in Hetzner console

DNS Problems:

• Nameserver Propagation: Can take 24-48 hours for full propagation
• API Rate Limits: Hetzner DNS has rate limits for API calls
• Domain Delegation: Ensure nameservers are updated at registrar

Debug Commands

# Test Hetzner Cloud API
curl -H "Authorization: Bearer $HETZNER_API_TOKEN"
     "https://api.hetzner.cloud/v1/servers"

# Test Hetzner DNS API
curl -H "Auth-API-Token: $HETZNER_DNS_API_TOKEN"
     "https://dns.hetzner.com/api/v1/zones"

# Check DNS propagation
dig NS your-domain.com
dig A tracker.your-domain.com

📖 Integration with Main Project

Environment Configuration

Hetzner configuration integrates with the main project's twelve-factor approach:

# infrastructure/config/environments/production-hetzner.env
PROVIDER=hetzner
# Token file paths (for reference)
HETZNER_API_TOKEN_CONFIG=infrastructure/config/providers/hetzner.env
HETZNER_DNS_TOKEN_CONFIG=infrastructure/config/providers/hetzner.env
TRACKER_DOMAIN=tracker.example.com
GRAFANA_DOMAIN=grafana.example.com
TRACKER_SUBDOMAIN=tracker.your-domain.com
GRAFANA_SUBDOMAIN=grafana.your-domain.com

Testing Integration

# Run Hetzner-specific tests
ENVIRONMENT=production-hetzner PROVIDER=hetzner make test-e2e

# Run cross-provider tests
make test-ci  # Includes all providers

🌍 Geographic Considerations

Hetzner Data Center Locations:

• Germany: Falkenstein, Nuremberg
• Finland: Helsinki
• US: Ashburn (Virginia)

Selection Criteria:

• Europe: Choose German DCs for GDPR compliance
• Global: Helsinki for Northern Europe, Ashburn for US East Coast
• Latency: Use Hetzner's looking glass to test connectivity

🔗 External Resources

Official Documentation

• Hetzner Cloud API - Cloud infrastructure API
• Hetzner DNS API - DNS management API
• Hetzner Console - Web management interface

Community Resources

• Hetzner Community - Official support forum
• r/hetzner - Reddit community
• awesome-hetzner - Community tools

This documentation provides comprehensive coverage of using Hetzner services for the Torrust Tracker Demo deployment.