SCOPE

This file helps you quickly understand what this repository is about, when it is relevant, and when it is not. It is intentionally lightweight and may be incomplete.

One-liner

S1 Infrastructure Substrate of the Railiance OAS Stack — Git-driven OS provisioning, security hardening, and server baseline using Terraform, cloud-init, and Ansible.

Core Idea

Railiance is structured as five independent repos per OAS Stack layer. This repo is S1 — the foundation. It provisions bare-metal/cloud servers (Hetzner, HostEurope), hardens the OS, manages secrets (SOPS/age), and validates the resulting baseline with Goss tests. S1 must be converged and verified before any higher layer (Kubernetes, platform, etc.) can run.

In Scope

OS provisioning via Terraform (Hetzner, HostEurope providers)
First-boot configuration via cloud-init
OS convergence via Ansible (base, security, sops_agent roles)
Security hardening and firewall rules
Secret management: SOPS/age encryption at rest in Git
Goss specification and test suite for OS baseline validation
Server inventory management (inventory/servers.yaml — source of truth)
SSH access management

Out of Scope

Kubernetes runtime → railiance-cluster (S2)
Platform services → railiance-platform (S3)
Developer tooling → railiance-enablement (S4)
Application deployments → railiance-apps (S5)
No cross-layer re-configuration from higher layers

Relevant When

Provisioning new servers for the Railiance stack
OS hardening, Ansible convergence, or Goss verification
Managing server inventory or SSH access
Rotating SOPS/age keys or updating secrets

Not Relevant When

Kubernetes, platform services, or application work (wrong layer)
Server is already provisioned and converged (use cluster/platform repos)

Current State

Status: active / productive
Implementation: single-server HostEurope baseline complete (RAIL-HO-WP-0001); server spec + test suite active (WP-0002); 5-repo stack restructure active (WP-0003)
Stability: high for single-server bootstrap; proven in production (92.205.62.239)
Usage: foundation for all Railiance deployments; used daily for convergence and verification

How It Fits

Upstream dependencies: Terraform, Ansible, SOPS/age (external tools); cloud provider APIs
Downstream consumers: railiance-cluster (S2) depends on a converged, verified OS from this layer; all higher layers transitively depend on S1
Often used with: railiance-cluster (next layer), ops-bridge (SSH tunnel for remote State Hub access)

Terminology

Preferred terms: OAS Stack Level S1, convergence, verification, SOPS/age, Goss specification, boundary rule
Potentially confusing terms: "convergence" = applying Ansible to reach desired state; "verification" = running Goss tests to validate it

railiance-cluster (S2) — consumes the OS baseline provided by S1
ops-bridge — used to reach local State Hub from remote HostEurope server

Getting Oriented

Start with: CLAUDE.md (session protocol, remote execution), README.md (provisioning workflow)
Key files / directories: inventory/servers.yaml (authoritative server list), ansible/ (playbooks/roles), terraform/ (provider configs), goss/ (spec + tests), docs/adr/ADR-003-railiance-5repo-stack-architecture.md
Entry points: make tf-plan, make tf-apply, make converge, make verify

Provided Capabilities

type: infrastructure
title: Server provisioning (Terraform)
description: Provision bare-metal and cloud servers on Hetzner and HostEurope via Terraform with cloud-init first-boot configuration.
keywords: [terraform, server, provisioning, hetzner, hosteurope, cloud-init, infrastructure]

type: infrastructure
title: OS hardening and convergence (Ansible)
description: Harden and converge server OS via Ansible (base, security, sops_agent roles) with Goss test suite for baseline validation.
keywords: [ansible, os, hardening, convergence, goss, security, baseline, validation]

type: security
title: Secret management (SOPS/age)
description: Manage encrypted secrets at rest in Git using SOPS/age — encrypt, rotate, and distribute secrets for Railiance infrastructure components.
keywords: [sops, age, secrets, encryption, gitops, key-rotation, credential]

Notes

Targets two servers: COULOMBCORE (92.205.130.254) and Railiance01 (92.205.62.239). State Hub access via ops-bridge — bridge up state-hub-coulombcore or bridge up state-hub-railiance01 from the workstation (see ADR-004).

4.6 KiB Raw Blame History