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`
- **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`)

---

## 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).