2025-09-13 02:00:25 +02:00
|
|
|
|
# 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-bootstrap.git
|
|
|
|
|
|
cd railiance-bootstrap
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
(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. Prepare your SSH key
|
|
|
|
|
|
|
|
|
|
|
|
If you don’t already have an SSH key:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
bin/railiance gen-ssh-key
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Upload the public key to your cloud provider or VM host.
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 3. 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
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 4. Provision a new VM
|
|
|
|
|
|
|
|
|
|
|
|
Recommended host specs:
|
|
|
|
|
|
- Ubuntu 24.04 LTS
|
|
|
|
|
|
- 2 vCPU, 4–8 GB RAM
|
|
|
|
|
|
- 60 GB SSD
|
|
|
|
|
|
|
|
|
|
|
|
When creating the VM, inject your SSH key and, if possible, apply the provided `cloudinit/user-data.yaml`.
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 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 installs prerequisites and sets up 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!
|
|
|
|
|
|
|
|
|
|
|
|
---
|
