railiance-cluster/QUICKSTART.md

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:

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:

bin/railiance doctor

This command will confirm prerequisites.

---

2. Prepare your SSH key

If you don’t already have an SSH key:

bin/railiance gen-ssh-key

Upload the public key to your cloud provider or VM host.

---

3. Create your inventory

Copy the example inventory:

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:

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:

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:

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:

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!

---