tegwick
660a63c674
Some checks failed
railiance-tests / smoke (push) Has been cancelled
T01: helm/gitea-values.yaml with postgresql-ha.pgpool.adminPassword
(fill REPLACE_WITH_PGPOOL_ADMIN_PASSWORD before helm upgrade)
T02: tests/smoke_kube.sh — add pgpool and postgresql-ha pod health checks
T03: tests/test_ha_failover.sh — D3 HA failover test script
T04: docs/incidents/2026-03-10-pgpool-missing-secret.md + README link
Also: make test-ha-failover target, Makefile .PHONY updated.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
85 lines
2.5 KiB
Markdown
85 lines
2.5 KiB
Markdown
# 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-bootstrap.git
|
||
cd railiance-bootstrap
|
||
|
||
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)
|
||
|
||
## 👥 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.
|
||
|