40e295e3bd
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a02994-7685-7940-bf34-3555b8256018
123 lines
4.4 KiB
Markdown
123 lines
4.4 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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](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
|
|
- 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 <name> --type ... --region ....
|
|
|
|
## 💻 5. Convergence
|
|
|
|
For adopted or newly provisioned servers, `railiance-infra` 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)
|
|
|
|
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](docs/verification.md).
|