Skip to content

hetzner

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

hetzner

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 
post-deployment.md
post-deployment.md
 
 

README.md

Hetzner Cloud Provider

This guide covers Hetzner-specific configuration for cloud deployments.

Overview

Hetzner Cloud provides affordable virtual servers with excellent performance. Ideal for production deployments.

Why Hetzner?

  • Cost-effective pricing
  • European data centers (Germany, Finland) + US locations
  • Simple, predictable billing
  • NVMe storage and modern hardware

Prerequisites

  • Hetzner Cloud account (sign up)
  • API token with read/write permissions
  • SSH key pair (see SSH keys guide)

Create API Token

  1. Log in to Hetzner Cloud Console
  2. Select your project (or create a new one)
  3. Navigate to Security → API Tokens
  4. Click Generate API Token
  5. Select Read & Write permissions
  6. Copy the token immediately - it won't be shown again!

⚠️ Security: Never commit API tokens to version control.

Hetzner-Specific Configuration

{
  "provider": {
    "provider": "hetzner",
    "api_token": "YOUR_HETZNER_API_TOKEN",
    "server_type": "cx22",
    "location": "nbg1",
    "image": "ubuntu-24.04"
  }
}
Field Description Example
provider Must be "hetzner" hetzner
api_token Your Hetzner API token hcloud_xxx…
server_type Server size/type cx22
location Datacenter location nbg1
image Operating system image ubuntu-24.04

Available Server Types

Type vCPUs RAM Storage Use Case
cx22 2 4 GB 40 GB Development, small trackers
cx32 4 8 GB 80 GB Production, medium traffic
cx42 8 16 GB 160 GB High-traffic trackers
cpx11 2 2 GB 40 GB Testing (AMD)
cpx21 3 4 GB 80 GB Development (AMD)

Available Locations

Location City Country
fsn1 Falkenstein Germany
nbg1 Nuremberg Germany
hel1 Helsinki Finland
ash Ashburn USA (East)
hil Hillsboro USA (West)

Available Images

Image Description
ubuntu-24.04 Ubuntu 24.04 LTS (recommended)
ubuntu-22.04 Ubuntu 22.04 LTS
debian-12 Debian 12 (Bookworm)
debian-11 Debian 11 (Bullseye)

Cost Estimation

Approximate monthly costs (check Hetzner pricing for current rates):

Server Type Monthly Cost (EUR)
cx22 ~€4.35
cx32 ~€8.70
cx42 ~€17.40

⚠️ Important: Remember to destroy resources when not in use to avoid charges.

Troubleshooting

API Token Invalid

Error: Failed to authenticate with Hetzner API

  • Verify your API token is correct
  • Ensure the token has Read & Write permissions
  • Check the token hasn't been revoked

Server Creation Failed

Possible causes:

  • Quota exceeded: Check your Hetzner project limits
  • Invalid server type: Verify the server type exists in your location
  • Image not available: Some images may not be available in all locations

SSH Connection Timeout

# Check if server is running in Hetzner Console
# Verify firewall rules (if using Hetzner Firewall) - port 22 must be open

# Check SSH key permissions
chmod 600 ~/.ssh/your_private_key

# Test manual SSH connection
ssh -i ~/.ssh/your_private_key -v torrust@<server-ip>

Cloud-init Timeout

# SSH into the server manually
ssh -i ~/.ssh/your_key root@<server-ip>

# Check cloud-init status
cloud-init status --wait

# View cloud-init logs
cat /var/log/cloud-init-output.log

Security Best Practices

  1. Never commit API tokens - Use environment variables or secure vaults
  2. Restrict SSH access - Consider using Hetzner Firewall
  3. Use strong SSH keys - Ed25519 or RSA 4096-bit minimum
  4. Regular updates - Keep server packages updated
  5. Disable root SSH access - For production, see SSH Root Access Guide

SSH Key Requirements

⚠️ Docker deployments require a passphrase-free SSH key (or SSH agent forwarding).

When you run the deployer inside a Docker container (the recommended approach for Hetzner), there is no SSH agent and no interactive terminal. A passphrase-protected private key will cause the provision step to fail with Permission denied (publickey,password).

Options:

  1. Remove the passphrase (recommended for dedicated deployment keys):

    ssh-keygen -p -f ~/.ssh/your_deployment_key
# Press Enter twice for an empty new passphrase

  2. Forward your SSH agent into the container (see SSH Keys Guide).

The create environment command will warn you if it detects a passphrase-protected key so you can resolve this before reaching provision.

For more detail on generating keys, removing passphrases, and security considerations, see the SSH Keys Guide.

SSH Key Behavior

Hetzner deployments configure SSH access through two mechanisms:

Mechanism User Purpose
OpenTofu hcloud_ssh_key root Emergency/debug access
cloud-init torrust Normal application access

Why both? If cloud-init fails, root SSH access provides a debugging path. Without it, a failed cloud-init would leave the server completely inaccessible.

For stricter security: You can disable root SSH access after deployment. See SSH Root Access on Hetzner for instructions.

Note: The SSH key appears in your Hetzner Console under Security → SSH Keys with the name torrust-tracker-vm-<environment>-ssh-key.

Related Documentation