From 0bfdf465c1fcef11e43e81733f947d4fe6577754 Mon Sep 17 00:00:00 2001
From: Bernd Worsch <bernd.worsch@gmail.com>
Date: Sat, 13 Sep 2025 02:00:25 +0200
Subject: [PATCH] chore: improved quickstart for newbies

---
 QUICKSTART.md | 129 +++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 123 insertions(+), 6 deletions(-)

diff --git a/QUICKSTART.md b/QUICKSTART.md
index bdd94d9..a3c1e6c 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -1,6 +1,123 @@
-# Railiance Bootkit Quickstart
-Run:
-  bin/railiance doctor
-  bin/railiance gen-ssh-key
-  bin/railiance cloudinit > user-data.yaml
-Then rent VM, seed with tools/seed_node.sh, and bootstrap with Ansible.
+# 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!
+
+---