# cit Ansible Infrastructure

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.

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

### Everything

Maintenance and full (re-)deployment.

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

### Maintenance

Regular system updates and patching.

```sh
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.

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

### Deploy cf-journex only

Deploy only the `cf-journex` Docker Compose stack without touching other services.

```sh
ansible-playbook -i inventories/hetzner playbooks/06-deploy-cf-journex.yml
```

### Rebuild Caddy

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

```sh
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

1. Add the host to `inventories/hetzner/hosts.yaml`
   * Set `ansible_host` and `ansible_user`
2. Bootstrap the VM as root

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

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

```bash
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

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

### Clone with a custom service name

```bash
./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.

```bash
./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](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`.