diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..cee1c2a --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,101 @@ +# 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 (per ADR-003) + +- 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 + +--- + +## Related / Overlapping Repositories + +- `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` + +--- + +## Notes + +Designed for remote execution from HostEurope (92.205.130.254). SSH reverse tunnel required for State Hub access: `ssh -R 8000:127.0.0.1:8000 tegwick@92.205.130.254`.