107 lines
3.2 KiB
Markdown
107 lines
3.2 KiB
Markdown
# NODE.DC Environment Contract
|
|
|
|
This contract separates local feature testing from deployed runtime.
|
|
|
|
## Profiles
|
|
|
|
`local`
|
|
|
|
- Runs Launcher, Engine, Ops/Gateway, AI Workspace Assistant, databases, and fixtures on the developer machine.
|
|
- May use the deployed AI Hub only as a thin relay for a remote Codex worker.
|
|
- Must not call production Launcher, Engine, Ops, Authentik, or Gateway endpoints.
|
|
|
|
`tunnel-local-e2e`
|
|
|
|
- Explicit escape hatch for Tailscale/ngrok-style testing.
|
|
- Same business services are still local, but relay URLs may use tunnel/private addresses.
|
|
- Must be opt-in through `NODEDC_ENV=tunnel-local-e2e`.
|
|
|
|
`staging`
|
|
|
|
- Deployed test stack with staging data and staging Authentik/OIDC clients.
|
|
- Used after local smoke is green.
|
|
|
|
`prod`
|
|
|
|
- Production data and production public domains.
|
|
- Only deploy artifacts that passed local and staging checks.
|
|
|
|
## URL Classes
|
|
|
|
- Browser URL: opened by a user browser.
|
|
- Internal service URL: used by one backend to call another backend.
|
|
- Relay URL: used only to move messages between a local assistant and a remote worker.
|
|
- Downstream app URL: used by an assistant adapter to read or mutate its owning app.
|
|
|
|
Do not mix these classes. A remote worker must not call Launcher, Engine, Ops, or Authentik directly in `local`.
|
|
|
|
## Local Remote Worker Chain
|
|
|
|
```text
|
|
local Engine
|
|
-> local AI Workspace Assistant
|
|
-> deployed AI Hub relay
|
|
-> remote Codex worker
|
|
-> deployed AI Hub relay
|
|
-> local AI Workspace Assistant
|
|
-> local Launcher / local Engine / local Ops
|
|
```
|
|
|
|
The deployed AI Hub is transport only. It must not decide product access, own app routes, or force production downstream URLs.
|
|
|
|
## Required Local Defaults
|
|
|
|
Engine local server:
|
|
|
|
```text
|
|
NODEDC_ENV=local
|
|
NODEDC_LAUNCHER_INTERNAL_URL=http://127.0.0.1:5173
|
|
NODEDC_LAUNCHER_ORIGIN=http://launcher.local.nodedc
|
|
AUTHENTIK_PUBLIC_BASE_URL=http://auth.local.nodedc
|
|
NODEDC_AI_WORKSPACE_ASSISTANT_URL=http://127.0.0.1:18082
|
|
OPS_RETENTION_ENABLED=false
|
|
```
|
|
|
|
Platform local stack:
|
|
|
|
```text
|
|
NODEDC_ENV=local
|
|
AI_WORKSPACE_HUB_PUBLIC_URL=wss://ai-hub.nodedc.ru/api/ai-workspace/hub
|
|
AI_WORKSPACE_HUB_INTERNAL_URL=https://ai-hub.nodedc.ru
|
|
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ENABLED=true
|
|
AI_WORKSPACE_ASSISTANT_ACTION_RELAY_ID=local-dev
|
|
```
|
|
|
|
The AI Hub URLs above are allowed only because they are relay URLs. Production app URLs such as `https://hub.nodedc.ru`, `https://engine.nodedc.ru`, `https://ops.nodedc.ru`, and `https://id.nodedc.ru` are forbidden in local app config.
|
|
|
|
Assistant action calls in local must use the relay route:
|
|
|
|
```text
|
|
remote worker assistant_action_call
|
|
-> deployed AI Hub /api/ai-workspace/hub/v1/assistant-relays/<relayId>/actions
|
|
-> local AI Workspace Assistant long-poll
|
|
-> local Launcher / Engine / Ops adapter
|
|
```
|
|
|
|
Do not route local assistant actions through the deployed Assistant or deployed product backends.
|
|
|
|
## Guardrail
|
|
|
|
Run the complete local testing gate before local AI Workspace testing:
|
|
|
|
```sh
|
|
sh platform/infra/scripts/check-local-test-system.sh
|
|
```
|
|
|
|
Run this narrower env-only guard when changing env files:
|
|
|
|
```sh
|
|
node platform/infra/scripts/check-local-environment-safety.mjs
|
|
```
|
|
|
|
Run the broader AI Workspace contract check before changing worker/assistant routing:
|
|
|
|
```sh
|
|
platform/infra/scripts/check-ai-workspace-config-contract.sh
|
|
```
|