Document local cloud startup and harden persistence

OpenJibo/docs/local-cloud-quickstart.md

@@ -0,0 +1,153 @@
+# Local OpenJibo Cloud Quickstart
+
+## Purpose
+
+This guide is for people who want to run OpenJibo locally.
+
+There are three different local paths:
+
+- `.NET cloud`: the current OpenJibo cloud implementation and the path we are actively shipping.
+- `Node cloud`: the legacy protocol oracle and reverse-engineering server. It is still useful and fun to run, but it is not the production direction.
+- `Playground`: a direct local Jibo ASR/TTS demo. It talks to Jibo on local ports and does not replace the cloud.
+
+For a physical Jibo, local cloud testing still assumes a controlled network, DNS/host routing, and certificate setup. See [device-bootstrap.md](device-bootstrap.md) for the device side.
+
+## Prerequisites
+
+Install:
+
+- .NET SDK for the repo target framework
+- Node.js and npm, for the Node oracle only
+- PowerShell, for the Windows helper scripts
+- `openssl`, for Linux live testing on port `443` with PEM certificate material
+
+Optional for real audio experiments:
+
+- `ffmpeg`
+- `whisper.cpp`
+
+## Run The .NET Cloud
+
+From the repo root:
+
+```powershell
+.\scripts\cloud\Start-OpenJiboDotNet.ps1
+```
+
+By default, this starts:
+
+- HTTPS: `https://localhost:24604`
+- HTTP: `http://localhost:24605`
+- health check: `http://localhost:24605/health`
+- websocket captures: `captures/websocket`
+- HTTP captures: `captures/http`
+
+Smoke check:
+
+```powershell
+.\scripts\cloud\Invoke-CloudSmoke.ps1 -BaseUrl http://localhost:24605
+```
+
+Run with the Azure Blob sample launch profile:
+
+```powershell
+.\scripts\cloud\Start-OpenJiboDotNet.ps1 -UseAzureBlobProfile
+```
+
+Run directly without a launch profile, useful when you want to supply all URLs and certificate settings by environment:
+
+```powershell
+$env:ASPNETCORE_URLS = "http://0.0.0.0:24605"
+.\scripts\cloud\Start-OpenJiboDotNet.ps1 -NoLaunchProfile
+```
+
+For a Linux live-device run on port `443`, reuse the existing PEM certificate material:
+
+```bash
+CERT_PEM=/path/to/cert.pem \
+KEY_PEM=/path/to/key.pem \
+ASPNETCORE_URLS="https://0.0.0.0:443;http://0.0.0.0:24605" \
+./scripts/cloud/start-dotnet-with-node-cert.sh
+```
+
+Then run:
+
+```bash
+./scripts/cloud/invoke-live-jibo-prep.sh
+```
+
+## Run The Node Cloud
+
+The Node cloud lives at `src/Jibo.Cloud/node`.
+
+From the repo root:
+
+```powershell
+.\scripts\cloud\Start-OpenJiboNode.ps1 -Install
+```
+
+After dependencies are installed once, you can usually run:
+
+```powershell
+.\scripts\cloud\Start-OpenJiboNode.ps1
+```
+
+Important details:
+
+- The Node server binds HTTPS on port `443`.
+- It expects `cert.pem` and `key.pem` in `src/Jibo.Cloud/node`.
+- Use the same certificate material that your controlled Jibo routing already trusts.
+- On Windows or Linux, binding port `443` may require an elevated shell.
+- Stop the .NET cloud first if it is also using port `443`.
+
+Manual equivalent:
+
+```powershell
+cd src\Jibo.Cloud\node
+npm install
+node .\open-jibo-link.js
+```
+
+The Node server writes discovery logs under `src/Jibo.Cloud/node/logs`.
+
+## Run Playground
+
+Playground is not a cloud server. It connects straight to a Jibo on your LAN:
+
+- ASR HTTP: `http://JIBO_IP:8088/asr_simple_interface`
+- ASR websocket: `ws://JIBO_IP:8088/simple_port`
+- TTS HTTP: `http://JIBO_IP:8089/tts_speak`
+
+From the repo root:
+
+```powershell
+.\scripts\cloud\Start-OpenJiboPlayground.ps1
+```
+
+When prompted, enter the Jibo IP address.
+
+Use Playground when you want to test the local ASR/TTS client behavior directly. Use the `.NET` or Node cloud when you want Jibo to boot and talk through the cloud-shaped protocol path.
+
+## Which One Should I Use?
+
+Use `.NET cloud` if you want the current OpenJibo behavior, release testing, captures, or anything close to the hosted future.
+
+Use `Node cloud` if you want the original prototype/oracle, protocol discovery, or a quick comparison against older behavior.
+
+Use `Playground` if you already know the robot IP and just want a local microphone-to-ASR-to-TTS loop through Jibo's local client interfaces.
+
+## Common Issues
+
+If `/health` fails, confirm the .NET cloud is running and use `http://localhost:24605/health` for local checks.
+
+If the Node server fails with a certificate error, add `cert.pem` and `key.pem` to `src/Jibo.Cloud/node`.
+
+If port `443` is busy, stop the other cloud server first or run the .NET cloud on the local dev ports.
+
+If a physical Jibo does not connect, confirm DNS/host routing for:
+
+- `api.jibo.com`
+- `api-socket.jibo.com`
+- `neo-hub.jibo.com`
+
+Then compare with the live runbook in [live-jibo-test-runbook.md](live-jibo-test-runbook.md).