Forgejo on Hetzner Cloud

This Terraform project deploys a self-hosted Forgejo Git hosting service on Hetzner Cloud with automatic SSL certificates via Caddy.

Architecture

• Server: Ubuntu 24.04 LTS on Hetzner Cloud
• Git Hosting: Forgejo (rootless container)
• Reverse Proxy: Caddy with automatic Let's Encrypt SSL
• SSH Configuration:
  • Port 2222: Admin SSH access
  • Port 22: Forgejo Git SSH access
• Firewall: Configured for web traffic and SSH

Features

• 🔒 Secure by default: Hardened SSH configuration, firewall rules
• 🔑 Automatic SSL: Let's Encrypt certificates via Caddy
• 🐳 Containerized: Docker Compose stack for easy management
• 🚀 Production-ready: Systemd service for automatic startup
• ⚡ Fast deployment: Single terraform apply command

Prerequisites

1. Hetzner Cloud account and API token
2. Domain name with DNS A record pointing to the server
3. SSH key pair for server access
4. Terraform >= 1.0 installed

Quick Start

1. Clone and Configure

git clone <your-repo>
cd forgejo-hetzner

2. Set Required Variables

Create a terraform.tfvars file:

# Required
hcloud_token    = "your-hetzner-api-token"
public_ssh_key  = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5... your-key"
domain_name     = "git.yourdomain.com"
acme_email      = "your-email@example.com"

# Optional (with defaults)
server_name     = "forgejo"
server_type     = "cpx11"
server_location = "hel1"
admin_user      = "ubuntu"

3. Deploy

terraform init
terraform plan
terraform apply

4. Access Your Forgejo Instance

After deployment (takes ~2-3 minutes):

1. Web Interface: Visit https://your-domain.com
2. Admin SSH: ssh ubuntu@<server-ip> -p 2222
3. Git SSH: Configure Git to use port 22 (default for Forgejo)

Configuration Variables

Variable	Description	Default	Required
hcloud_token	Hetzner Cloud API token	-	✅
public_ssh_key	SSH public key for server access	-	✅
domain_name	Domain for Forgejo (must point to server)	droneaid.kenmac.nl	❌
acme_email	Email for Let's Encrypt notifications	you@example.com	❌
server_name	Name for the Hetzner server	forgejo	❌
server_type	Hetzner server type	cpx11	❌
server_location	Hetzner datacenter location	hel1	❌
admin_user	Admin username for server	ubuntu	❌

Server Types

Common Hetzner server types:

• cpx11: 2 vCPU, 4 GB RAM, 40 GB SSD (~€4.15/month)
• cx22: 2 vCPU, 4 GB RAM, 40 GB SSD (~€5.83/month)
• cax11: 2 vCPU ARM, 4 GB RAM, 40 GB SSD (~€3.29/month)

Locations

Available Hetzner locations:

• hel1: Helsinki, Finland
• fsn1: Falkenstein, Germany
• nbg1: Nuremberg, Germany
• ash: Ashburn, Virginia, USA

Network Configuration

Port	Service	Description
22	Forgejo SSH	Git operations (clone, push, pull)
80	HTTP	Redirects to HTTPS
443	HTTPS	Web interface (Caddy → Forgejo)
2222	Admin SSH	Server administration

Post-Deployment Setup

1. Complete Forgejo Setup

1. Visit https://your-domain.com
2. Follow the initial setup wizard
3. Configure your Git repositories

2. Configure Git Client

For Git operations over SSH:

# Clone repositories
git clone git@your-domain.com:username/repo.git

# Or configure SSH for custom port (if needed)
# Add to ~/.ssh/config:
Host your-domain.com
    Port 22
    User git

3. Server Management

Connect to your server for maintenance:

ssh ubuntu@<server-ip> -p 2222

# Check service status
sudo systemctl status forgejo-stack

# View logs
sudo docker compose -f /opt/forgejo/docker-compose.yml logs -f

# Restart services
sudo systemctl restart forgejo-stack

File Structure

.
├── main.tf              # Main Terraform configuration
├── variables.tf         # Input variables
├── outputs.tf          # Output values
├── cloud-init.yaml     # Server initialization script
├── terraform.tfvars   # Your variable values (create this)
└── README.md          # This file

Maintenance

Updating Forgejo

1. SSH into the server: ssh ubuntu@<server-ip> -p 2222
2. Update the Docker image:

   cd /opt/forgejo
   sudo docker compose pull
   sudo docker compose up -d

Backup

Important directories to backup:

• /opt/forgejo/data/ - Git repositories and database
• /opt/forgejo/conf/ - Forgejo configuration
• /opt/caddy/data/ - SSL certificates

SSL Certificates

Caddy automatically manages Let's Encrypt certificates. They renew automatically every 60 days.

Troubleshooting

Common Issues

1. SSL Certificate Issues: Ensure your domain's A record points to the server IP
2. SSH Connection Issues: Check if you're using the correct port (2222 for admin, 22 for Git)
3. Firewall Issues: Verify Hetzner Cloud firewall rules are applied

Useful Commands

# Check service status
sudo systemctl status forgejo-stack

# View container logs
sudo docker logs forgejo
sudo docker logs caddy

# Restart the entire stack
sudo systemctl restart forgejo-stack

# Check Caddy configuration
sudo docker exec caddy caddy validate --config /etc/caddy/Caddyfile

Security Notes

• SSH password authentication is disabled
• Root login is restricted to SSH keys only
• Admin SSH runs on non-standard port (2222)
• Firewall rules restrict access to necessary ports only
• SSL certificates are managed automatically

Cost Estimation

Approximate monthly costs (EUR, as of 2024):

• Server (cpx11): €4.15
• Traffic: Usually free (20TB included)
• Total: ~€4.15/month

License

This project is open source. Forgejo is MIT licensed.