Ty
e5e179e541
Operator can run make bootstrap/install through S2 using nemohermes/openshell wrappers; docs and implement queue updated. No S3+ and no push.
116 lines
3.7 KiB
Markdown
116 lines
3.7 KiB
Markdown
# Install
|
||
|
||
**Status:** Stages S0–S2 implemented. S3–S7 pending.
|
||
|
||
## Stages
|
||
|
||
| 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)).
|
||
|
||
---
|
||
|
||
## 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
|
||
# or
|
||
make bootstrap
|
||
```
|
||
|
||
**Idempotent:** if Docker is already installed and running, the script exits immediately.
|
||
|
||
**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.
|