This repository contains the Ansible based infrastructure setup for cit services running on Hetzner virtual machines. It covers initial host bootstrapping, common system configuration, Docker and Docker Compose based application deployment, and ongoing maintenance.

Parts of this setup are inspired by and derived from existing open source projects. See the Open Source Acknowledgements section at the end.

Requirements

Ansible installed locally
SSH access to Hetzner hosts defined in inventories/hetzner/hosts.yaml
Host specific variables in inventories/hetzner/host_vars/
Debian based target systems

Structure

inventories/hetzner/hosts.yaml
- Host definitions and group assignments
inventories/hetzner/host_vars/
- Host specific configuration
- Includes Docker Compose projects and service configuration
docker_compose_applications/
- Docker Compose services, one "stack" per folder

Common Playbooks

The following playbooks cover the most common workflows. Replace HOSTNAME with the inventory hostname.

Init VM

First bootstrap of a freshly created VM. This is usually run once and requires root access.

ansible-playbook -e ansible_user=root -i inventories/hetzner playbooks/00-init_hetzer_vm.yaml

Everything

Maintenance and full (re-)deployment.

ansible-playbook -i inventories/hetzner playbooks/01-everything.yaml

Maintenance

Regular system updates and patching.

ansible-playbook -i inventories/hetzner playbooks/02-maintenance.yaml

"compose up"

Deploy or refresh Docker Compose applications after configuration changes or when adding new services.

ansible-playbook -i inventories/hetzner playbooks/04-compose-up.yml

Rebuild Caddy

Rebuild and reload Caddy only. Useful when reverse proxy configuration changed and full service restarts should be avoided.

ansible-playbook -i inventories/hetzner playbooks/05-rebuild-caddy.yml

Notes

Some services such as Stirling PDF have a slow startup time. When only reverse proxy configuration changes are required, prefer the Caddy rebuild playbook.

Adding a new Hetzner VM

Add the host to inventories/hetzner/hosts.yaml
- Set ansible_host and ansible_user
Bootstrap the VM as root

ansible-playbook -e ansible_user=root -i inventories/hetzner -l HOSTNAME playbooks/00-init_hetzer_vm.yaml

Add host variables and group assignments in inventories/hetzner/host_vars/
Run the desired playbook, usually the full setup

ansible-playbook -i inventories/hetzner -l HOSTNAME playbooks/01-everything.yaml

Adding a new service

The helper script add-service.sh can be used to add new services quickly.

Clone and register a Git repository

./add-service.sh git@github.com:example/repo.git

Clone with a custom service name

./add-service.sh git@github.com:example/repo.git my-service

Create a local scaffold

Creates a new service directory with a template compose.yaml including the shared caddy_net network.

./add-service.sh my-service

After adding or modifying services, deploy them using the compose up playbook.

Open Source Acknowledgements

Parts of this repository are based on work from the following project:

CCCHH ansible infra repository
- Source: https://git.hamburg.ccc.de/CCCHH/ansible-infra
- License: MIT

A copy of the MIT license can be found at licenses/ccchh-ansible_mit_license.