Implement install stages S0–S2: bootstrap, env, model and vision smoke.

Operator can run make bootstrap/install through S2 using nemohermes/openshell wrappers; docs and implement queue updated. No S3+ and no push.
2026-07-27 11:47:34 -07:00
parent 998e32e871
commit e5e179e541
14 changed files with 893 additions and 60 deletions
@@ -1,31 +1,115 @@
 # Install

-**Status:** Outline from approved design. Scripts stubbed until **build**.
+**Status:** Stages S0–S2 implemented. S3–S7 pending.

 ## Stages

-| Stage | Where | Outcome |
-|-------|--------|---------|
-| S0 | Human | Host per [DEPLOYER_HOST.md](DEPLOYER_HOST.md) |
-| S0b | Host script | Docker installed if missing |
-| S1 | Host script | Repo env, `.env` from `.env.example` |
-| S2 | Host script | Main + aux vision config; vision smoke |
-| S3–S5 | Host → Compose / `nemohermes` | Stack, sandbox, policy, skills |
-| S6 | Host script | Doctor green |
-| S7 | Owner + operator connect helpers | Name assistant; connect **their** SaaS/channels |
+| Stage | Where | Outcome | Status |
+|-------|--------|---------|--------|
+| S0 | Human | Host per [DEPLOYER_HOST.md](DEPLOYER_HOST.md) | ✅ Procedural |
+| S0b | Host script | Docker installed if missing | ✅ Implemented |
+| S1 | Host script | Repo env, `.env` from `.env.example` | ✅ Implemented |
+| S2 | Host script | Main + aux vision config; vision smoke | ✅ Implemented |
+| S3–S5 | Host → Compose / `nemohermes` | Stack, sandbox, policy, skills | ⏳ Pending |
+| S6 | Host script | Doctor green | ⏳ Pending |
+| S7 | Owner + operator connect helpers | Name assistant; connect **their** SaaS/channels | ⏳ Pending |

 ## Platform commands (normative)

 All mutations: `nemohermes` / `openshell` (see [design/research/platform-notes.md](../design/research/platform-notes.md)).

-## Intended entrypoints
+---
+
+## S0: Host baselining
+
+Follow [DEPLOYER_HOST.md](DEPLOYER_HOST.md) to prepare the host:
+
+1. Provision a Linux host (cloud VM, bare metal).
+2. Install OS updates.
+3. Create a deploy user with sudo access.
+4. Install `nemohermes` and `openshell` CLIs.
+5. Clone this repository.
+
+## S0b: Docker bootstrap

 ```bash
 ./scripts/bootstrap.sh
-./scripts/install.sh
-./scripts/doctor.sh
+# or
+make bootstrap
 ```

-## After install
+**Idempotent:** if Docker is already installed and running, the script exits immediately.

-[SETUP_UX.md](SETUP_UX.md) · [design/scenarios.md](../design/scenarios.md) (S1–S5).
+**What it checks:**
+- `docker info` succeeds → skip install.
+- OS family detection (Debian/Ubuntu or RHEL/Fedora).
+- Installs Docker, adds user to `docker` group, verifies daemon.
+
+## S1: Repository environment
+
+```bash
+./scripts/install/s1-env.sh
+# or
+make install-s1
+```
+
+**What it does:**
+1. If `.env` does not exist, copies `.env.example` to `.env`.
+2. Validates that all required keys are present and non-empty:
+   - `LUMINA_SANDBOX` — sandbox name (default: `hermes`)
+   - `LUMINA_INFERENCE_BASE_URL` — inference endpoint URL
+   - `LUMINA_INFERENCE_MODEL` — model identifier
+   - `LUMINA_VISION_MODEL` — vision model identifier
+3. Fails with clear messages if keys are missing or empty.
+
+**Edit `.env`** with your actual values before running S2. See `.env.example` for all keys and descriptions.
+
+**Never commit `.env` with real secrets.** It is in `.gitignore`.
+
+## S2: Model + vision configuration
+
+```bash
+./scripts/install/s2-models.sh
+# or
+make install-s2
+```
+
+**What it does:**
+1. Loads `.env` and validates required keys.
+2. Checks that `nemohermes` and `openshell` CLIs are available.
+3. Verifies the inference endpoint is reachable (`/v1/models`).
+4. If the OpenShell gateway is connected, configures the inference route via `openshell inference set`.
+5. Runs the **vision smoke test**:
+   - Probes `/v1/models` for `multimodal` capability tag.
+   - Falls back to a minimal chat completion if capability tags are not exposed.
+6. **Fails loudly** (non-zero exit) if vision capability cannot be confirmed.
+
+**If the gateway is not yet connected:** the script validates the endpoint and skips the `openshell` write. S3+ will handle full gateway configuration.
+
+## Run all stages (S0b–S2)
+
+```bash
+./scripts/install.sh
+# or
+make install
+# or
+make install-s0-s2
+```
+
+## After install (S0–S2)
+
+- Verify `.env` values are correct for your environment.
+- Continue with S3+ when implemented (compose stack, sandbox creation, policy, skills).
+- See [SETUP_UX.md](SETUP_UX.md) for owner-facing setup after full install.
+- See [design/scenarios.md](../design/scenarios.md) (S1–S5) for operational scenarios.
+
+## UAT host notes
+
+This repository was tested on a live host with:
+- `nemohermes` v0.0.93, `openshell` v0.0.85
+- Sandbox: `hermes` (default)
+- Gateway: `nemoclaw` at `https://127.0.0.1:8080`
+- Inference: OpenAI-compatible endpoint with multimodal model
+- Docker: present and running
+
+Scripts are idempotent on this configuration.