124 lines
2.0 KiB
Markdown
124 lines
2.0 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-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!
|
||
|
||
---
|