Hetzner Temporary Host

Overview

Rapidly deploy services from GitHub repositories to temporary Hetzner Cloud VMs with automatic ZeroTier network integration. This skill automates the entire workflow: provision a VM, join it to your existing ZeroTier network, clone a GitHub repo, deploy with Docker Compose, and verify the service is healthy. Perfect for testing, demos, or temporary service deployments.

When to Use This Skill

Use this skill when users request:

• Deploying a service from GitHub to a temporary server
• Quick testing of containerized applications in the cloud
• Creating disposable demo environments
• Deploying services to a specific ZeroTier network
• Setting up temporary infrastructure that can be easily torn down
• Running short-lived services without permanent infrastructure

Quick Start

To deploy a service from GitHub to a temporary host:

1. Set required configuration:
   • Hetzner Cloud API token (from https://console.hetzner.cloud/)
   • ZeroTier API token (from https://my.zerotier.com/account)
   • ZeroTier network ID (from existing network)
   • GitHub repository URL
2. Copy the Terraform template from assets/terraform-hetzner-temp-host/ to working directory
3. Configure SSH key path (defaults to ~/.ssh/id_ed25519)
4. Deploy using scripts/deploy_host.sh or manually with Terraform
5. Service automatically deploys via Docker Compose after host provisioning
6. Health checks verify service is running correctly

Core Capabilities

1. Host Configuration

The Terraform templates support flexible host configurations:

Server Types (CCX Line):

• ccx13: 2 vCPU, 8GB RAM, 80GB NVMe (~$8.90/month, ~$0.012/hour) - Default
• ccx23: 4 vCPU, 16GB RAM, 160GB NVMe (~$17.80/month, ~$0.025/hour)
• ccx33: 8 vCPU, 32GB RAM, 240GB NVMe (~$35.60/month, ~$0.049/hour)

Datacenters:

• hillsboro: Hillsboro, OR, USA (hil-dc1) - Default
• singapore: Singapore (sin-dc1)
• germany: Falkenstein, Germany (fsn1-dc14)

Example Configuration:

host_name         = "temp-api-server"
server_type       = "ccx13"
datacenter        = "hillsboro"
github_repo_url   = "https://github.com/user/my-service"
zerotier_network  = "1c33c1ced02a5a44"

2. Service Deployment

Docker Compose Workflow:

1. Host provisioned on Hetzner Cloud
2. Docker and Docker Compose automatically installed
3. GitHub repository cloned to /opt/app
4. docker compose up -d executed in repo directory
5. Health checks verify service started successfully
6. Connection details provided in outputs

Requirements:

• Repository must contain a docker-compose.yml or compose.yaml file
• Service should expose health check endpoint (optional but recommended)
• Public repositories work out of the box
• Private repositories require SSH key or access token configuration

Supported Deployment Patterns:

• Single container services
• Multi-container applications
• Services with databases and dependencies
• Applications with volume mounts
• Services requiring environment variables (via .env file in repo)

3. ZeroTier Integration

Join Existing Network:

• Connects to your pre-configured ZeroTier network
• Automatically installs ZeroTier One client
• Joins specified network and waits for authorization
• Host becomes accessible via ZeroTier IP
• Can be authorized manually or automatically (depending on network settings)

Configuration Methods:

Method A: Environment Variable (Recommended for security)

export ZEROTIER_NETWORK_ID='1c33c1ced02a5a44'
export ZEROTIER_API_TOKEN='your-zerotier-api-token'
export HCLOUD_TOKEN='your-hetzner-api-token'

Method B: Terraform Variables

zerotier_network = "1c33c1ced02a5a44"
zerotier_api_token = "your-zerotier-api-token"

Method C: Mixed (Network ID in config, token in env)

export ZEROTIER_API_TOKEN='your-zerotier-api-token'
export HCLOUD_TOKEN='your-hetzner-api-token'

zerotier_network = "1c33c1ced02a5a44"

Authorization:

• If network has auto-authorization enabled, host joins automatically
• Otherwise, manually authorize at https://my.zerotier.com
• Check authorization status: zerotier-cli listnetworks

4. Health Checks

Automatic Service Verification:

• Checks that Docker containers are running
• Optionally pings HTTP/HTTPS health endpoint
• Verifies ZeroTier connectivity
• Reports status in Terraform outputs

Health Check Options:

# Basic check (Docker containers running)
health_check_enabled = true

# HTTP endpoint check
health_check_url = "http://localhost:8080/health"
health_check_url = "http://localhost:3000/api/status"

# Disable health checks
health_check_enabled = false

Example Health Check Output:

Outputs:
health_status = {
  "docker_running" = true
  "containers_up" = 3
  "endpoint_healthy" = true
  "zerotier_connected" = true
}

5. Deployment Methods

Method A: Using the Helper Script (Recommended)

The scripts/deploy_host.sh script automates the entire deployment:

# Copy script to working directory
cp scripts/deploy_host.sh .
chmod +x deploy_host.sh

# Set required tokens
export HCLOUD_TOKEN='your-hetzner-api-token'
export ZEROTIER_API_TOKEN='your-zerotier-api-token'
export ZEROTIER_NETWORK_ID='your-network-id'

# Deploy with repository URL
./deploy_host.sh https://github.com/user/my-service

# Deploy with custom configuration
./deploy_host.sh https://github.com/user/my-api my-api-host ccx23 singapore

The script will:

1. Verify API tokens and network ID are set
2. Verify SSH key pair exists
3. Generate terraform.tfvars with configuration
4. Initialize Terraform
5. Show plan and prompt for confirmation
6. Deploy host and join ZeroTier network
7. Clone repo and deploy with Docker Compose
8. Run health checks
9. Display connection and service information

Method B: Manual Deployment

For more control:

1. Copy Terraform templates:

   cp -r assets/terraform-hetzner-temp-host/* ./
   

2. Create terraform.tfvars:

   hcloud_token        = "your-hetzner-api-token"
   zerotier_api_token  = "your-zerotier-api-token"
   zerotier_network    = "1c33c1ced02a5a44"
   host_name           = "my-temp-host"
   github_repo_url     = "https://github.com/user/my-service"
   server_type         = "ccx13"
   datacenter          = "hillsboro"
   ssh_private_key_path = "~/.ssh/id_ed25519"
   health_check_enabled = true
   health_check_url     = "http://localhost:8080/health"
   

3. Deploy:

   terraform init
   terraform plan
   terraform apply
   

4. View outputs:

   terraform output
   terraform output zerotier_ip
   terraform output service_url
   

6. Accessing the Host and Service

SSH Access:

# Via public IP
ssh root@<public-ip>

# Via ZeroTier IP (after authorization)
ssh root@<zerotier-ip>

# Get SSH command from Terraform
terraform output -raw ssh_command

Service Access:

# Get service URL
terraform output service_url

# Access via public IP
curl http://<public-ip>:<port>

# Access via ZeroTier (from any device on the network)
curl http://<zerotier-ip>:<port>

Docker Management:

# View running containers
ssh root@<host> 'docker ps'

# View logs
ssh root@<host> 'docker compose -f /opt/app/docker-compose.yml logs'

# Restart services
ssh root@<host> 'docker compose -f /opt/app/docker-compose.yml restart'

7. Host Management

Check service status:

terraform output health_status
ssh root@<host> 'docker ps'
ssh root@<host> 'zerotier-cli listnetworks'

Redeploy service:

ssh root@<host> 'cd /opt/app && git pull && docker compose down && docker compose up -d'

Destroy host:

terraform destroy

Cost Management:

• Hourly billing means you only pay for actual usage
• Always destroy temporary hosts when done
• ccx13 costs $0.012/hour ($0.29/day)
• Set calendar reminders to tear down test environments

Common Workflows

Workflow 1: Deploy a Simple Web Service

User request: "Deploy my web app from GitHub to a temporary server on my ZeroTier network"

1. Get ZeroTier network ID from https://my.zerotier.com
2. Set environment variables:

   export HCLOUD_TOKEN='...'
   export ZEROTIER_API_TOKEN='...'
   export ZEROTIER_NETWORK_ID='...'
   

3. Use helper script:

   ./deploy_host.sh https://github.com/user/webapp my-webapp
   

4. Authorize host on ZeroTier Central if needed
5. Access service via ZeroTier IP
6. Destroy when done: terraform destroy

Workflow 2: Test a Multi-Container Application

User request: "I need to test my microservices stack with Redis and Postgres before deploying to production"

1. Ensure GitHub repo has complete docker-compose.yml with all services
2. Deploy to temporary host:

   ./deploy_host.sh https://github.com/user/microservices test-stack ccx23
   

3. Health check verifies all containers are running
4. Access services via public IP or ZeroTier
5. Run integration tests
6. Tear down: terraform destroy

Workflow 3: Demo Environment for Client

User request: "Create a temporary demo environment for a client presentation tomorrow"

1. Deploy service to temporary host:

   ./deploy_host.sh https://github.com/company/demo-app client-demo
   

2. Get public IP from outputs: terraform output public_ip
3. Share URL with client: http://<public-ip>:<port>
4. After demo, destroy environment: terraform destroy
5. Total cost: ~$0.50 for 2-day deployment

Workflow 4: Test Feature Branch

User request: "I want to deploy a feature branch to test it in a real environment"

1. Push feature branch to GitHub
2. Modify github_repo_url in terraform.tfvars:

   github_repo_url = "https://github.com/user/repo#feature-branch"
   

3. Deploy: terraform apply
4. Test the feature via ZeroTier network
5. Destroy when testing complete

Troubleshooting

SSH key pair not found:

• Ensure both ~/.ssh/id_ed25519 and ~/.ssh/id_ed25519.pub exist
• Generate: ssh-keygen -t ed25519
• Or set custom path: export SSH_KEY_PATH="/path/to/key"

GitHub clone fails:

• Public repos: Check URL is correct
• Private repos: Add SSH key to GitHub or use personal access token in URL
• Format: https://username:token@github.com/user/repo

Docker Compose not found in repo:

• Verify repo contains docker-compose.yml or compose.yaml
• Check file is in root directory of repo
• Test locally: git clone <repo> && cd <repo> && docker compose config

Containers fail to start:

• Check logs: ssh root@<host> 'docker compose -f /opt/app/docker-compose.yml logs'
• Verify environment variables if needed (add .env file to repo)
• Check resource requirements match server type
• Verify all required ports are available

ZeroTier node not joining:

• Check network ID is correct
• Verify ZeroTier API token has permissions
• Wait 30-60 seconds for service to start
• Check status: ssh root@<host> 'zerotier-cli listnetworks'

ZeroTier not authorized:

• Go to https://my.zerotier.com
• Find your network
• Authorize the new member
• Check authorization: zerotier-cli listnetworks

Health checks failing:

• Verify containers are running: docker ps
• Check health endpoint URL is correct
• Ensure service is listening on correct port
• Try accessing directly: curl http://localhost:<port>
• Disable health checks temporarily: health_check_enabled = false

Provisioner timeout:

• Increase timeout in main.tf provisioner blocks
• Check SSH connectivity manually
• Verify firewall rules allow SSH
• Check SSH key permissions: chmod 600 ~/.ssh/id_ed25519

Resources

scripts/

• deploy_host.sh: Complete deployment automation with validation and interactive prompts
• health_check.sh: Service health verification script (used by Terraform provisioners)

assets/

• terraform-hetzner-temp-host/: Terraform templates for temporary host deployment
  • main.tf: Core infrastructure (server, firewall, ZeroTier, provisioning)
  • variables.tf: Input variables with validation and defaults
  • outputs.tf: Connection info, service details, health status
  • versions.tf: Terraform and provider requirements
  • terraform.tfvars.example: Example configuration

Best Practices

1. Always destroy temporary hosts when finished to avoid unnecessary costs
2. Use environment variables for secrets (tokens, keys) instead of hardcoding
3. Enable health checks to verify successful deployment
4. Tag hosts appropriately with descriptive names for easy identification
5. Set reminders to tear down test environments after demos/testing
6. Use ZeroTier for secure access instead of exposing services publicly
7. Test locally first with docker compose up before deploying to cloud
8. Monitor costs at https://console.hetzner.cloud/
9. Use appropriate server sizes - start small, scale up if needed
10. Document cleanup procedures for team members

Cost Examples

Based on Hetzner Cloud hourly billing:

Scenario	Server	Duration	Cost
Quick test	ccx13	2 hours	~$0.02
Day of testing	ccx13	24 hours	~$0.29
Week demo	ccx13	7 days	~$2.00
Load testing	ccx23	4 hours	~$0.10
Client presentation	ccx13	3 days	~$0.87

Remember: Costs accumulate while the host exists. Always terraform destroy when finished!