tegwick
01903a17bb
Update all operational references to reflect the new repo name per ADR-003 (OAS S2 Cluster Runtime). Historical text in docs preserved. Gitea remote URL updated locally (Gitea repo rename is a manual step). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
150 lines
2.9 KiB
Markdown
150 lines
2.9 KiB
Markdown
# Railiance Newcomer Quickstart
|
||
|
||
Welcome to **Railiance** 🚂✨ — an opinionated Infrastructure‑as‑Code framework.
|
||
This guide is written for newcomers who want to set up their very first Railiance host.
|
||
|
||
---
|
||
|
||
## 0. Get the code
|
||
|
||
Clone this repository locally and enter it:
|
||
|
||
```bash
|
||
git clone https://<your-gitea-domain>/<org-or-user>/railiance-cluster.git
|
||
cd railiance-cluster
|
||
```
|
||
|
||
(Replace `<your-gitea-domain>` and `<org-or-user>` with your setup.)
|
||
|
||
---
|
||
|
||
## 1. Check your environment
|
||
|
||
Make sure you have these installed locally:
|
||
|
||
- Git
|
||
- Ansible
|
||
- Python 3
|
||
- SSH client
|
||
|
||
Check with:
|
||
|
||
```bash
|
||
bin/railiance doctor
|
||
```
|
||
|
||
This command will confirm prerequisites.
|
||
|
||
---
|
||
|
||
## 2. Provision a new VM
|
||
|
||
Recommended host specs:
|
||
- Ubuntu 24.04 LTS
|
||
- 2 vCPU, 4–8 GB RAM
|
||
- 60 GB SSD
|
||
|
||
```bash
|
||
bin/railiance plan-host
|
||
```
|
||
|
||
When creating the VM, inject your SSH key and, if possible, apply the provided `cloudinit/user-data.yaml`.
|
||
|
||
---
|
||
|
||
## 3. Prepare your SSH key
|
||
|
||
If you don’t already have an SSH key:
|
||
|
||
```bash
|
||
bin/railiance gen-ssh-key
|
||
```
|
||
|
||
### Upload your SSH public key to your cloud provider or VM host
|
||
|
||
Once your key pair is generated (`~/.ssh/id_<KEY>.pub`), copy the public key to the VM.
|
||
Replace `<IP>` with your server’s public IP and `<USER>` with the default login user (commonly `ubuntu` or `root`).
|
||
|
||
```bash
|
||
scp ~/.ssh/id_<KEY>.pub <USER>@<IP>:/home/<USER>/authorized_keys.tmp
|
||
ssh <USER>@<IP> "mkdir -p ~/.ssh && cat ~/authorized_keys.tmp >> ~/.ssh/authorized_keys && rm ~/authorized_keys.tmp && chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys"
|
||
```
|
||
|
||
This will:
|
||
|
||
- copy your public key to the host,
|
||
- append it to ~/.ssh/authorized_keys,
|
||
- set correct permissions.
|
||
|
||
After this, you should be able to log in without a password:
|
||
|
||
```bash
|
||
ssh <USER>@<IP>
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Create your inventory
|
||
|
||
Copy the example inventory:
|
||
|
||
```bash
|
||
cp ansible/hosts.ini.example ansible/hosts.ini
|
||
```
|
||
|
||
Edit `ansible/hosts.ini` and add the IP or hostname of your Railiance host.
|
||
|
||
Test that Ansible can reach it:
|
||
|
||
```bash
|
||
ansible -i ansible/hosts.ini all -m ping
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Seed the host
|
||
|
||
Log in to the host and run the seed script:
|
||
|
||
```bash
|
||
tools/seed_node.sh
|
||
```
|
||
|
||
This will clone the repo on the host, set up housekeeping, and get ready for provisioning.
|
||
|
||
---
|
||
|
||
## 6. Bootstrap with Ansible
|
||
|
||
From your local machine:
|
||
|
||
```bash
|
||
ansible-playbook -i ansible/hosts.ini ansible/bootstrap.yml
|
||
```
|
||
|
||
This runs in two stages:
|
||
1. **Harden** — disables root/password SSH login, enables UFW (ports 22/6443/8472), installs fail2ban
|
||
2. **Bootstrap** — installs base packages and a single‑node k3s cluster
|
||
|
||
---
|
||
|
||
## 7. Verify
|
||
|
||
Run the smoke test:
|
||
|
||
```bash
|
||
tests/smoke_kube.sh
|
||
```
|
||
|
||
If successful, you now have a working Railiance host 🎉
|
||
|
||
---
|
||
|
||
## Next steps
|
||
|
||
- Explore `ansible/` playbooks for services (e.g., uptime-kuma, postgres).
|
||
- Read `docs/README.md` for philosophy and design.
|
||
- Join the community and contribute improvements!
|
||
|
||
---
|