diff --git a/architecture/deployment-blueprint.md b/architecture/deployment-blueprint.md new file mode 100644 index 0000000..63ef40b --- /dev/null +++ b/architecture/deployment-blueprint.md @@ -0,0 +1,270 @@ +# EVOLV Deployment Blueprint + +## Purpose + +This document turns the current EVOLV architecture into a concrete deployment model. + +It focuses on: + +- target infrastructure layout +- container/service topology +- environment and secret boundaries +- rollout order from edge to site to central + +It is the local source document behind the wiki deployment pages. + +## 1. Deployment Principles + +- edge-first operation: plant logic must continue when central is unavailable +- site mediation: site services protect field systems and absorb plant-specific complexity +- central governance: external APIs, analytics, IAM, CI/CD, and shared dashboards terminate centrally +- layered telemetry: InfluxDB exists where operationally justified at edge, site, and central +- configuration authority: `tagcodering` should become the source of truth for configuration +- secrets hygiene: tracked manifests contain variables only; secrets live in server-side env or secret stores + +## 2. Layered Deployment Model + +### 2.1 Edge node + +Purpose: + +- interface with PLCs and field assets +- execute local Node-RED logic +- retain local telemetry for resilience and digital-twin use cases + +Recommended services: + +- `evolv-edge-nodered` +- `evolv-edge-influxdb` +- optional `evolv-edge-grafana` +- optional `evolv-edge-broker` + +Should not host: + +- public API ingress +- central IAM +- source control or CI/CD + +### 2.2 Site node + +Purpose: + +- aggregate one or more edge nodes +- host plant-local dashboards and engineering visibility +- mediate traffic between edge and central + +Recommended services: + +- `evolv-site-nodered` or `coresync-site` +- `evolv-site-influxdb` +- `evolv-site-grafana` +- optional `evolv-site-broker` + +### 2.3 Central platform + +Purpose: + +- fleet-wide analytics +- API and integration ingress +- engineering lifecycle and releases +- identity and governance + +Recommended services: + +- reverse proxy / ingress +- API gateway +- IAM +- central InfluxDB +- central Grafana +- Gitea +- CI/CD runner/controller +- optional broker for asynchronous site/central workflows +- configuration services over `tagcodering` + +## 3. Target Container Topology + +### 3.1 Edge host + +Minimum viable edge stack: + +```text +edge-host-01 + - Node-RED + - InfluxDB + - optional Grafana +``` + +Preferred production edge stack: + +```text +edge-host-01 + - Node-RED + - InfluxDB + - local health/export service + - optional local broker + - optional local dashboard service +``` + +### 3.2 Site host + +Minimum viable site stack: + +```text +site-host-01 + - Site Node-RED / CoreSync + - Site InfluxDB + - Site Grafana +``` + +Preferred production site stack: + +```text +site-host-01 + - Site Node-RED / CoreSync + - Site InfluxDB + - Site Grafana + - API relay / sync service + - optional site broker +``` + +### 3.3 Central host group + +Central should not be one giant undifferentiated host forever. It should trend toward at least these responsibility groups: + +```text +central-ingress + - reverse proxy + - API gateway + - IAM + +central-observability + - central InfluxDB + - Grafana + +central-engineering + - Gitea + - CI/CD + - deployment orchestration + +central-config + - tagcodering-backed config services +``` + +For early rollout these may be colocated, but the responsibility split should remain clear. + +## 4. Compose Strategy + +The current repository shows: + +- `docker-compose.yml` as a development stack +- `temp/cloud.yml` as a broad central-stack example + +For production, EVOLV should not rely on one flat compose file for every layer. + +Recommended split: + +- `compose.edge.yml` +- `compose.site.yml` +- `compose.central.yml` +- optional overlay files for site-specific differences + +Benefits: + +- clearer ownership per layer +- smaller blast radius during updates +- easier secret and env separation +- easier rollout per site + +## 5. Environment And Secrets Strategy + +### 5.1 Current baseline + +`temp/cloud.yml` now uses environment variables instead of inline credentials. That is the minimum acceptable baseline. + +### 5.2 Recommended production rule + +- tracked compose files contain `${VARIABLE}` placeholders only +- real secrets live in server-local `.env` files or a managed secret store +- no shared default production passwords in git +- separate env files per layer and per environment + +Suggested structure: + +```text +/opt/evolv/ + compose.edge.yml + compose.site.yml + compose.central.yml + env/ + edge.env + site.env + central.env +``` + +## 6. Recommended Network Flow + +### 6.1 Northbound + +- edge publishes or syncs upward to site +- site aggregates and forwards selected data to central +- central exposes APIs and dashboards to approved consumers + +### 6.2 Southbound + +- central issues advice, approved config, or mediated requests +- site validates and relays to edge where appropriate +- edge remains the execution point near PLCs + +### 6.3 Forbidden direct path + +- enterprise or internet clients should not directly query PLC-connected edge runtimes + +## 7. Rollout Order + +### Phase 1: Edge baseline + +- deploy edge Node-RED +- deploy local InfluxDB +- validate PLC connectivity +- validate local telemetry and resilience + +### Phase 2: Site mediation + +- deploy site Node-RED / CoreSync +- connect one or more edge nodes +- validate site-local dashboards and outage behavior + +### Phase 3: Central services + +- deploy ingress, IAM, API, Grafana, central InfluxDB +- deploy Gitea and CI/CD services +- validate controlled northbound access + +### Phase 4: Configuration backbone + +- connect runtime layers to `tagcodering` +- reduce config duplication in flows +- formalize config promotion and rollback + +### Phase 5: Smart telemetry policy + +- classify signals +- define reconstruction rules +- define authoritative layer per horizon +- validate analytics and auditability + +## 8. Immediate Technical Recommendations + +- treat `docker/settings.js` as development-only and create hardened production settings separately +- split deployment manifests by layer +- define env files per layer and environment +- formalize healthchecks and backup procedures for every persistent service +- define whether broker usage is required at edge, site, central, or only selectively + +## 9. Next Technical Work Items + +1. create draft `compose.edge.yml`, `compose.site.yml`, and `compose.central.yml` +2. define server directory layout and env-file conventions +3. define production Node-RED settings profile +4. define site-to-central sync path +5. define deployment and rollback runbook