tegwick
703c57d91c
Update all operational references to reflect the new repo name per ADR-003 (OAS S1 Infrastructure Substrate). Historical text in ADRs and state-hub-inbox files preserved as-is. Gitea remote URL updated locally (Gitea repo rename is a manual step). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
106 lines
3.8 KiB
Markdown
106 lines
3.8 KiB
Markdown
# 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-infra
|
|
```
|
|
|
|
## 📦 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
|
|
|