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:

```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. 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!

---