railiance-infra/README.md

# RailianceHosts

**Tagline:** Git-driven automation for secure, self-reliant servers.

RailianceHosts is an open-source control repo that provisions and manages servers on Hosteurope and Hetzner Cloud entirely from Git. It combines **Terraform** for lifecycle management, **cloud-init** for first-boot configuration, and **Ansible** for convergence. All secrets live in-repo encrypted with **SOPS** and are unlocked with your single **age** master key (which you keep in your password manager). The minimal server registry in `inventory/servers.yaml` is the source of truth.

## Quickstart

0. **Clone Repo**: clone the repo
1. **Prerequisites**: terraform >= 1.7, ansible >= 2.16, age, sops.
2. **Secrets Management**: Generate master key (age), provide it to sops and provide your SSH key.
3. **Setup Provider**: Create account, select payment option, establish API token.
4. **Provisioning**: Plan and apply `inventory/servers.yaml` to add hosts with terraform.
5. **Convergence**: Setup security and tooling with ansible.


## 🚀 0. Clone Repo

First, clone this repository to your workstation:

```bash
git clone https://<your-gitea-host>/coulomb/railliance-hosts.git
cd railiance-hosts
```

## 📦 1. Prerequisites

To use RailianceHosts, make sure you have the following tools installed on your workstation:

- **Git** → for version control  
- **age** → for key management and encryption ([Install guide](docs/age-keys.md))  
- **SOPS** → for managing encrypted secrets ([SOPS GitHub](https://github.com/getsops/sops))  
- **Terraform** → for provisioning infrastructure ([Terraform Downloads](https://developer.hashicorp.com/terraform/downloads))  
- **Ansible** → for server configuration ([Ansible Installation Guide](https://docs.ansible.com/ansible/latest/installation_guide/))  
- **Make** → to run the included `Makefile` tasks  

### Example installation (Ubuntu/Debian)

```bash
# System tools
sudo apt update
sudo apt install -y git make ansible

# Terraform
sudo apt install -y wget unzip
wget https://releases.hashicorp.com/terraform/1.9.5/terraform_1.9.5_linux_amd64.zip
unzip terraform_1.9.5_linux_amd64.zip
sudo mv terraform /usr/local/bin/

# age 
sudo apt install age 

# SOPS Get the latest release (example: v3.10.2 — check GitHub for updates)
wget https://github.com/getsops/sops/releases/download/v3.10.2/sops_3.10.2_amd64.deb
sudo apt install ./sops_3.10.2_amd64.deb
```

## 🔑 2. Secrets Management

### Generate Age Masterkey and establish SOPS

This project uses [SOPS](https://github.com/getsops/sops) with [age](https://age-encryption.org) for secret encryption.  
To set up your own key and configure SOPS, follow the guide here:

➡️ [Managing Age Keys](docs/age-keys.md)


### SSH Access Preparations

Learn how to add your SSH key and test connectivity after provisioning:

➡️ [SSH Access & Connectivity Test](docs/ssh-access.md)

TL;DR
 - put your public key into keys/admin_ssh.pub

## 💻 3. Setup Provider

You need register an account and set it up for API access:
 - register
 - choose payment method
 - generate api-key
 - store api-key in secrets safely

## 🚀 4. Provisioning

How to declare hosts and bring them up on Hetzner:

➡️ [Provisioning Servers](docs/provisioning.md)

TL;DR
 - Define servers in inventory/servers.yaml (name, region, type, image, ssh_user, labels/role).
 - Provision with make tf-apply (or make apply to also run Ansible).
 - One-shot helper: scripts/hcloud_new_server.sh <name> --type ... --region ....

## 💻 5. Convergence

After provisioning a server with Terraform, RailianceHosts uses [Ansible](https://docs.ansible.com/) to **converge** hosts into a secure, baseline state.  
This includes admin user setup, SSH hardening, firewall rules, essential tooling, and secret handling.

📖 See the full guide here: [Convergence Documentation](docs/convergence.md)


xxx