railiance-infra/SCOPE.md

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 and the canonical ownership home for infrastructure substrate facts. It provisions bare-metal or cloud servers (Hetzner, HostEurope), hardens the OS, manages secrets (SOPS/age), and validates the resulting baseline with Goss tests. Future reef-* repos will model purpose-bound substrates, but the source-backed OS baseline, inventory, and server identity facts start here. 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
• Canonical S1 identity and substrate-fact base for future reef-* repos
• Source-backed server and workstation substrate facts needed by higher-layer architecture work

---

Out of Scope

• Kubernetes runtime → railiance-cluster (S2)
• Platform services → railiance-platform (S3)
• Developer tooling → railiance-enablement (S4)
• Application deployments → railiance-apps (S5)
• Workload execution semantics or rail contracts → rail-* repos
• Purpose-specific reef repo ownership and workload-placement policy beyond the S1 source-backed substrate facts
• 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
• Preparing or validating first-wave reef-* rollout identity facts

---

Not Relevant When

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

---

Current State

• Status: maintained / productive
• Implementation: HostEurope substrate baseline active for Railiance01 and CoulombCore; server spec + test suite active; first reef rollout source map defined. Railiance is classified along four repo-family axes (railiance-*, rail-*, rapp-*, reef-*), of which five railiance-* repos cover S1–S5; this file previously said "5-repo stack architecture", which predates that model
• Stability: high for the current single-server and transitional two-server substrate reality; proven in production on 92.205.62.239
• Usage: foundation for all Railiance deployments; canonical S1 source for higher-layer and future reef planning. railiance-hosts is superseded by this repo and carries a banner saying so; its retirement is pending in railiance-master
• Open security work: RAIL-HO-WP-0009 — the base role declared the k3s API open to Anywhere while the live host was source-restricted by hand, so converging would have exposed the Kubernetes API. The allowlist is now declarative (k3s_api_allowed_sources / k3s_api_revoked_sources) but has not yet been converged, so the live host still carries two stale grants to rotated operator addresses

---

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
• Future substrate-boundary consumers: first-wave reef-* repos should project from the source-backed facts here rather than creating a second S1 inventory
• 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

---

Related / Overlapping

• railiance-cluster (S2) — consumes the OS baseline provided by S1
• railiance-hosts — predecessor or migration-duplicate S1 line; not the canonical repo for new architecture work
• 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/reef-first-wave-source-map.md, 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 current server substrates: CoulombCore (92.205.130.254) and Railiance01 (92.205.62.239). The first-wave reef rollout also recognizes a grouped operator workstation substrate. State Hub access uses ops-bridge — bridge up state-hub-coulombcore or bridge up state-hub-railiance01 from the workstation (see ADR-004).