From b46d163baebdd99de0b52ee06c14b44051ba187f Mon Sep 17 00:00:00 2001
From: James Allenby <JamesAllenby@protonmail.com>
Date: Sun, 5 Jul 2026 23:00:25 +0100
Subject: [PATCH] doc: add quick start guide

---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/README.md b/README.md
index 38e7996..a3a0719 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,30 @@
 # Home Infrastructure
 
+## Quick Start
+
+Get started with a local Kubernetes cluster which can be used to design and test
+new configuration before pushing them to real machines.
+
+1. Login with Proton Pass and start the SSH daemon.
+
+    ```shell
+    pass-cli login
+    pass-cli ssh-agent daemon start
+    export SSH_AUTH_SOCK="$HOME/.ssh/proton-pass-agent.sock"
+    ```
+
+2. Launch Incus virtual machines
+
+    ```shell
+    just up
+    ```
+
+3. Tear down the Incus virtual machines
+
+    ```shell
+    just down
+    ```
+
 ## Setup
 
 ```shell
@@ -15,3 +40,19 @@ The Kolibri automation user is used for all other playbooks and has permissions
 ```shell
 ansible-playbook -i ansible/inventories/bare_metal/hosts.yaml ansible/playbooks/provision.yaml -K -e ansible_user=<your_interactive_user>
 ```
+
+## Local Testing with Incus
+
+```shell
+just up
+```
+
+```shell
+just headlamp
+```
+
+> The above command runs the Flatpak version of Headlamp which may not have permissions
+> to access the Kubernetes config file copied from the instance.
+>
+> You should run `flatpak override --user --filesystem=$(pwd) io.kinvolk.Headlamp`
+> to ensure that Headlamp can access the directory contents.