railiance-infra/README.md

railiance-infra

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

railiance-infra is the canonical S1 ownership repo for the Railiance infrastructure substrate. It manages two adopted Host Europe servers through source-backed inventory, Ansible convergence, and recurring Goss verification. A separate Terraform and cloud-init path provisions only records explicitly declared as provider-managed Hetzner resources. Selected provider material lives in-repo encrypted with SOPS/age; host convergence does not distribute the private age key.

Future reef-* repos will model purpose-bound substrate boundaries such as reef-railiance or reef-ops-workstations, but the source-backed S1 inventory, hardening baseline, and OS convergence facts stay here.

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: Validate inventory; plan/apply only provider-managed Hetzner records. Adopted Host Europe records are never Terraform resources.
5. Convergence: Setup security and tooling with ansible.

🚀 0. Clone Repo

First, clone this repository to your workstation:

git clone https://<your-gitea-host>/coulomb/railiance-infra.git
cd railiance-infra

📦 1. Prerequisites

To use railiance-infra, make sure you have the following tools installed on your workstation:

• Git → for version control
• age → for key management and encryption (Install guide)
• SOPS → for managing encrypted secrets (SOPS GitHub)
• Terraform → for provisioning infrastructure (Terraform Downloads)
• Ansible → for server configuration (Ansible Installation Guide)
• Make → to run the included Makefile tasks

Example installation (Ubuntu/Debian)

# 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 with age for secret encryption.
To set up your own key and configure SOPS, follow the guide here:

➡️ Managing Age Keys

SSH Access Preparations

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

➡️ SSH Access & Connectivity Test

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

TL;DR

• Run make validate-inventory after editing inventory/servers.yaml.
• Put Hetzner-only fields under provisioning on a lifecycle_mode: provider-managed record.
• Review make tf-plan; an apply additionally requires APPROVE_TF_APPLY=YES.
• One-shot helper: scripts/hcloud_new_server.sh --type ... --region ....

💻 5. Convergence

For adopted or newly provisioned servers, railiance-infra uses Ansible 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

Routine make verify and make s1-handoff runs are read-only on managed hosts. Updating the installed Goss surface is deliberately separate and requires an exact APPROVE_VERIFY_REFRESH value; see Server Verification.