# 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` - **Firewall posture**: `RAIL-HO-WP-0009` finished. k3s API is tunnel-only (ADR-005); live `Railiance01` UFW matches the declaration. CoulombCore UFW stays unmanaged (`ufw_manage: false`) - **Resource evidence**: `RAIL-HO-WP-0008` finished. Non-secret identity, capacity observations, and host-ops labor live under `docs/evidence/resource-hosteurope-railiance01/` --- ## 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 ```capability 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] ``` ```capability 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] ``` ```capability 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).