docs

Author: AlchemiistCreative

docs/getting-started.md

@@ -2,8 +2,6 @@
 
 > ⚠️ **Active Development:** OpenHVX is not production-ready. This guide targets **contributors and early testers**.
 
----
-
 ## Prerequisites
 
 - Windows host with **Hyper-V** (for Agent tests)
@@ -38,16 +36,13 @@ This initializes the **platform-wide administrator** via the Admin Auth API.
 > - The `mode` parameter defines the registration behavior:
 >   - `once`: create only if missing (409 if already exists)
 >   - `reset`: reset password only if user exists
->   - `upsert`: create if missing, or reset if exists (recommended for bootstrap)
+>   - `upsert`: create if missing, or reset if exists (**recommended for bootstrap**)
 > - Replace `x-api-key` and credentials as needed.
 
 ### Curl
 
 ```bash
-curl -k -X POST "https://admin-api.openhvx.local/api/v1/admin/auth/register?mode=upsert" \
-  -H "content-type: application/json" \
-  -H "x-api-key: example" \
-  --data-binary '{"email":"admin@openhvx.local","password":"3x4mpl3"}'
+curl -k -X POST "https://admin-api.openhvx.local/api/v1/admin/auth/register?mode=upsert"   -H "content-type: application/json"   -H "x-api-key: example"   --data-binary '{"email":"admin@openhvx.local","password":"3x4mpl3"}'
 ```
 
 **Expected response (example):**
@@ -68,6 +63,84 @@ curl -k -X POST "https://admin-api.openhvx.local/api/v1/admin/auth/register?mode
 > - Avoid exposing the API key in your shell history: export it to a variable (`export ADMIN_REGISTER_KEY=...`) and use `-H "x-api-key: $ADMIN_REGISTER_KEY"`.
 > - Change the password and registration key in real environments.
 
+## Set up the Image Repository (with **openhvx-img**)
+
+OpenHVX expects a JSON index describing available base images (cloud-init compatible `.vhdx` files).  
+The easiest way to generate this index is via the **[OpenHVX/openhvx-img](https://github.com/OpenHVX/openhvx-img)** tool.
+
+### 1) Place your images on a shared path
+
+Store your `.vhdx` base images in a shared folder accessible by all Hyper‑V Agents — typically an SMB share.
+
+Example layout on the share:
+
+```
+\\fileserver\EXAMPLE\
+├─ public/
+│  ├─ Rocky-10-GenericCloud-Base.vhdx
+│  ├─ Ubuntu-22.04-LTS.vhdx
+│  └─ ...
+└─ _index/
+```
+
+### 2) Generate the image index
+
+Run the `openhvx-img` tool with the `-root` and `-output` options to automatically scan your repository and produce the index file.
+
+```bash
+openhvx-img -root \\fileserver\EXAMPLE\ -output \\fileserver\EXAMPLE\_index\images.json
+```
+
+This creates a JSON structure like:
+
+```json
+{
+  "schema": "openhvx.images/v1",
+  "generatedAt": "2025-09-07T09:20:02Z",
+  "images": [
+    {
+      "id": "Rocky-10-GenericCloud-Base",
+      "scope": "public",
+      "tenantId": null,
+      "name": "Rocky-10-GenericCloud-Base",
+      "path": "\\192.168.1.37\\openhvx\\public\\Rocky-10-GenericCloud-Base.vhdx",
+      "os": "linux",
+      "arch": "x86_64",
+      "gen": 2,
+      "sizeBytes": 1501560832,
+      "mtime": "2025-09-07T09:17:04Z"
+    }
+  ]
+}
+```
+
+> 💡 The `path` values must correspond to actual network locations accessible by the Agents.
+
+### 3) Mount the index in the Controller
+
+Bind the `_index` directory in the Controller container and set the `IMAGES_INDEX_PATH` environment variable.
+
+**docker-compose.override.yml (example):**
+
+```yaml
+services:
+  controller:
+    volumes:
+      - /mnt/openhvx/_index:/share/_index:ro
+    environment:
+      - IMAGES_INDEX_PATH=/share/_index/images.json
+```
+
+### 4) Verify access from the Agent
+
+Make sure that each Hyper‑V host running an Agent can access the `public/` folder (where the images are stored).
+
+Example test (Windows PowerShell):
+
+```powershell
+Test-Path "\\fileserver\EXAMPLE\public\Rocky-10-GenericCloud-Base.vhdx"
+```
+
 ## Build Agent Tools (Windows helpers)
 
 These binaries are required by the PowerShell Agent to create **cloud-init ISOs** and to bridge **serial consoles**.
@@ -133,5 +206,5 @@ This will:
 ## Next Steps
 
 - Read: **Overview → Architecture & Features**
-- Contribute: open issues/PRs on GitHub → [https://github.com/openhvx](https://github.com/openhvx)
+- Contribute: open issues/PRs on GitHub → https://github.com/openhvx
 - Roadmap & known limitations: _(coming soon)_