# Railiance Documentation

Welcome to **Railiance** — an opinionated framework for Infrastructure-as-Code.  
Think of it as *Rails for Ops*: convention over configuration, productivity first, reproducible everywhere.

---

## 🚀 What is Railiance?

Railiance is the **self-reliant infrastructure bootstrap** for Coulomb and beyond.  
From two bare Linux servers, a Git repo, and valid credentials, you can rebuild a full Kubernetes-based environment with:

- **Automated provisioning** (Ansible, Helm, k3s)  
- **Git-driven state** (ArgoCD / Flux)  
- **AI-ready automation** with OODA loop (Observe, Orient, Decide, Act)  
- **End-to-end reproducibility** — no hidden steps, no snowflake servers  

---

## 🌱 Core Principles

1. **Convention over configuration**  
   Opinionated defaults remove friction.  

2. **Don’t repeat yourself (DRY)**  
   Single source of truth in Git, reused everywhere.  

3. **Automated OODA**  
   - *Observe*: collect telemetry.  
   - *Orient*: AI interprets state.  
   - *Decide*: human reviews & authorizes.  
   - *Act*: automation applies changes.  

4. **Self-Reliance**  
   Everything can be rebuilt from scratch, with no external dependencies beyond Git + credentials.  

5. **Calm Ops**  
   Systems should be simple, resilient, and predictable.  

---

## 📂 Repo Layout

- `ansible/` — bootstrap playbooks (OS setup, k3s install, etc.)  
- `helm/` — Helm charts for services  
- `k8s/` — raw manifests & overlays  
- `tests/` — automated validation of infra steps  
- `docs/` — documentation & contributor guides  
- `tools/` — helper scripts (e.g. repo bootstrap)  

---

## 🛠 Getting Started

1. **Clone the repo**  
   ```bash
   git clone <your-gitea-url>/railiance-cluster.git
   cd railiance-cluster
   
2. **Prepare your config**
    Edit ~/.railiance_gitea.conf with your Gitea URL, user, and token.
    (Never commit this file!)

3. **Run bootstrap**
   Use the playbooks in ansible/ to turn a bare Ubuntu server into a Kubernetes host.

4. **Deploy services**
   Install baseline services via Helm from the helm/ directory.

## Incidents

- [2026-03-10 — pgpool CrashLoopBackOff on PostgreSQL HA failover](incidents/2026-03-10-pgpool-missing-secret.md)

## Operations

- [Deployment lifecycle](deployment-lifecycle.md)

## 👥 Contributing

See CONTRIBUTING.md for rules, coding style, and workflow.

## 🌍 Vision

Railiance is more than infra scripts: it’s the foundation of self-empowering infrastructure,
where humans and AI agents collaborate to manage systems with trust, clarity, and calmness.

From bare metal to resilient clusters, in one repo.