From 580c45f494a439a91a800c07a6be9b9fddb17797 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Thu, 30 Apr 2026 02:27:08 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20parity=20rig=20=E2=80=94=20concrete=20m?= =?UTF-8?q?xaccessgw=20setup=20recipe?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaces the placeholder "configure an API key per gateway.md" with the actual commands that worked end-to-end on this dev box: - Build both halves (Worker x86 net48, Server net10) - apikey init-db + apikey create-key with the seven scopes the parity test exercises (session:*, invoke:*, events:read, metadata:read) - Three env-var overrides at server startup — capturing real lessons learned standing the rig up: * Kestrel__Endpoints__Http__Url = http://localhost:5120 * Kestrel__Endpoints__Http__Protocols = Http2 (gRPC needs h2c on plain HTTP — without this flag the client gets HTTP_1_1_REQUIRED) * MxGateway__Worker__ExecutablePath = absolute path to the built worker (appsettings.json's relative path drops \net48 and the server can't resolve it) - Note that workers spawn lazily on first OpenSession, not at server startup — so port-listening is necessary but not sufficient evidence the gateway is healthy. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/v2/Galaxy.ParityRig.md | 60 +++++++++++++++++++++++++------------ 1 file changed, 41 insertions(+), 19 deletions(-) diff --git a/docs/v2/Galaxy.ParityRig.md b/docs/v2/Galaxy.ParityRig.md index a718abe..06d7961 100644 --- a/docs/v2/Galaxy.ParityRig.md +++ b/docs/v2/Galaxy.ParityRig.md @@ -45,34 +45,56 @@ Per `~/.claude/projects/.../memory/`: ### 1. Build + run mxaccessgw -The gateway source is at `c:\Users\dohertj2\Desktop\mxaccessgw\`. From -that repo: +The gateway source is at `c:\Users\dohertj2\Desktop\mxaccessgw\`. +Build both halves — the worker has to be x86 net48 (MxAccess COM +bitness), the server is .NET 10: ```powershell cd C:\Users\dohertj2\Desktop\mxaccessgw -dotnet publish src\MxGateway.Server -c Release -o C:\publish\MxAccessGw +dotnet build src\MxGateway.Worker -c Release # produces bin\x86\Release\net48\MxGateway.Worker.exe +dotnet build src\MxGateway.Server -c Release # produces bin\Release\net10.0\MxGateway.Server.dll ``` -Configure: - -- An API key. Pick anything stable (e.g. `parity-suite-key`) and put it in - whichever config file `MxGateway.Server` reads — see `mxaccessgw/gateway.md` - for the current shape. -- ClientName for the worker's MxAccess registration — set to `OtOpcUa-Parity` - so it doesn't collide with `OtOpcUa-Galaxy.Host`. -- Bind to `http://localhost:5120` (default in `launchSettings.json`). - -Run it as a console app for the first session — easier to inspect logs. -NSSM-wrap it later if the rig becomes long-lived: +Initialize the auth database and mint an API key. The CLI mode is +gated by an `apikey` first-arg prefix: ```powershell -C:\publish\MxAccessGw\MxGateway.Server.exe +$env:MxGateway__ApiKeyPepper = "parity-rig-dev-pepper" # any stable string for dev +$srv = "C:\Users\dohertj2\Desktop\mxaccessgw\src\MxGateway.Server\bin\Release\net10.0\MxGateway.Server.dll" + +dotnet $srv apikey init-db # → "init-db: initialized" + +dotnet $srv apikey create-key ` + --key-id parity-rig ` + --display-name "OtOpcUa-Parity" ` + --scopes "session:open,session:close,invoke:read,invoke:write,invoke:secure,events:read,metadata:read" +# → "API key: mxgw_parity-rig_" ← capture this; you can't list secrets later ``` -The worker should log a successful `Register` against MxAccess after a -few seconds. If it loops on `Register` failures, that's an MxAccess-side -problem — the legacy `OtOpcUaGalaxyHost` going through the same COM -stack is a known-good reference point. +Save that exact key string for `OTOPCUA_PARITY_GW_API_KEY` in step 2. + +Run the server with three env-var overrides — the defaults don't +quite match what gRPC + the parity test need: + +```powershell +$env:MxGateway__ApiKeyPepper = "parity-rig-dev-pepper" # MUST match the create-key invocation +$env:Kestrel__Endpoints__Http__Url = "http://localhost:5120" +$env:Kestrel__Endpoints__Http__Protocols = "Http2" # gRPC needs h2c on plain HTTP +$env:MxGateway__Worker__ExecutablePath = ` + "C:\Users\dohertj2\Desktop\mxaccessgw\src\MxGateway.Worker\bin\x86\Release\net48\MxGateway.Worker.exe" + # appsettings.json's relative path is missing the \net48 segment; absolute path sidesteps that + +dotnet $srv +# → "Now listening on: http://localhost:5120" +``` + +The worker spawns lazily on the first OpenSession RPC — there's no +worker process visible in Task Manager until the first session. If +the worker can't spawn, the server returns `Failed to open session +session-…` with a `WorkerProcessLaunchException` in the server log. + +NSSM-wrap it later if the rig becomes long-lived; for first-pass +provisioning a console window is easier to inspect. ### 2. Set the parity env vars