@@ -0,0 +1,23 @@
|
||||
# Backup und Restore – v1.5.0
|
||||
|
||||
Die Release-Skripte sichern die drei zustandsbehafteten Produktbereiche konsistent während eines kurzen Maintenance-Stopps: NeuroForge `/app/data`, Agent `/app/data` sowie Knowledge-Produktion, Staging und Knowledge-Backups auf dem Host.
|
||||
|
||||
## Backup
|
||||
|
||||
```sh
|
||||
./scripts/backup-data.sh /srv/glpi-neuroforge-backups
|
||||
```
|
||||
|
||||
Das Skript führt zuerst den Produktions-Preflight aus, stoppt `neuroforge-worker`, `agent`, `neuroforge` und `knowledge`, kopiert die beiden Named Volumes sowie die drei Knowledge-Verzeichnisse und erzeugt `MANIFEST` plus `SHA256SUMS`. Danach werden die Services wieder gestartet.
|
||||
|
||||
## Restore
|
||||
|
||||
```sh
|
||||
./scripts/restore-data.sh /srv/glpi-neuroforge-backups/20260827T071500Z
|
||||
```
|
||||
|
||||
Restore validiert zuerst alle SHA-256-Prüfsummen, stoppt dieselben Services, leert die beiden Daten-Volumes kontrolliert über `busybox:1.36`, stellt alle Datenbereiche wieder her und startet die Services anschließend. `BACKUP_HELPER_IMAGE` kann auf ein intern freigegebenes Helper-Image gesetzt werden.
|
||||
|
||||
## Pflichtprüfung nach Restore
|
||||
|
||||
Nach jedem Restore müssen `docker compose ps`, NeuroForge `/readyz`, Knowledge `/api/health`, Agent `/readyz` und ein read-only Control-Center-Aufruf geprüft werden. GLPI-Schreibautomation bleibt bis zum erfolgreichen Smoke-Test deaktiviert (`DRY_RUN=true`, `AUTO_REPLY=false`, `AUTO_PRIORITY=false`, `AUTO_ESCALATION=false`).
|
||||
+10
-7
@@ -8,11 +8,11 @@
|
||||
| Produktive KB schreiben | nein | ja | nein | nein | nein |
|
||||
| KB-Staging schreiben | nein | ja | über getrennten KB Integration Token möglich | nein | nein |
|
||||
| KB-Staging promoten | nein | ja | nein | nein | nein |
|
||||
| Knowledge-Vektoren upserten | ja, App Key | nein | ja | ja | nein |
|
||||
| Knowledge-Vektoren suchen | ja, App Key | nein | ja | ja | nein |
|
||||
| Knowledge-Vektoren upserten | ja, Integration Token | nein | ja | ja | nein |
|
||||
| Knowledge-Vektoren suchen | ja, Integration Token | nein | ja | ja | nein |
|
||||
| NeuroForge Config ändern | nein | nein | nein | ja | nein |
|
||||
| NeuroForge Secrets lesen/rotieren | nein | nein | nein | ja | nein |
|
||||
| Systemstatus lesen | eigene Readiness | eigene Health | Stats mit App Key | ja | aggregiert read-only |
|
||||
| Systemstatus lesen | eigene Readiness | eigene Health | Stats mit Control-Read-Token | ja | aggregiert read-only |
|
||||
| Obsidian-Export | Live-Sicht inkl. GLPI-Relations | kanonische KB | nein | nein | verlinkt Ziel-UI |
|
||||
| Human Outcome erfassen | ja, authentifizierter Techniker | nein | empfängt nur validated outcome | sichtbar/admin | Status read-only |
|
||||
| Trusted Outcome-Source setzen | nein | nein | **serverseitig fest** | ja | nein |
|
||||
@@ -22,11 +22,14 @@
|
||||
## Credentials
|
||||
|
||||
- `NEUROFORGE_ADMIN_TOKEN`: nur Betreiber/Admin.
|
||||
- `NEUROFORGE_APP_API_KEY`: Agent und read-only Control-Stats; keine Admin-Config.
|
||||
- `NEUROFORGE_APP_API_KEY`: allgemeine App-API; keine Admin-Config und keine Integration-Schreibpfade.
|
||||
- `NEUROFORGE_INTEGRATION_TOKEN`: ausschließlich Agent/Knowledge-Integration, Events und validierte Outcomes.
|
||||
- `NEUROFORGE_CONTROL_READ_TOKEN`: ausschließlich read-only NeuroForge-Stats/Graph für das Control Center.
|
||||
- `NEUROFORGE_WORKER_TOKEN`: nur NeuroForge Worker.
|
||||
- `NEUROFORGE_METRICS_TOKEN`: nur Metrics-Scraper.
|
||||
- `KB_INTEGRATION_TOKEN`: ausschließlich maschineller Staging-Ingress.
|
||||
- `BASIC_AUTH_USER/PASSWORD`: Knowledgebase-Editor.
|
||||
- `CONTROL_BASIC_AUTH_USER/PASSWORD`: Control Center; `/healthz` bleibt öffentlich.
|
||||
- `WEB_USERNAME/PASSWORD`: Agent-Webzugang.
|
||||
- `SEARXNG_SECRET`: nur optionaler SearXNG-Container/Betreiber.
|
||||
- GLPI-Credentials: ausschließlich Agent.
|
||||
@@ -65,19 +68,19 @@ Folgende Informationen bleiben absichtlich außerhalb des NeuroForge-Learnings:
|
||||
|
||||
| Akteur | Outcome suchen | Outcome lernen | Outcome superseden | Quality Replay | Auto-Reply autorisieren |
|
||||
|---|---:|---:|---:|---:|---:|
|
||||
| GLPI Agent App-Key | ja, nur aktives validated Outcome API | ja, accepted/corrected | indirekt nur über neue korrigierte Revision | nein über NeuroForge; eigener read-only Agent-Endpunkt | nur über bestehende Agent-Policies + freigegebene KB |
|
||||
| GLPI Agent Integration-Token | ja, nur aktives validated Outcome API | ja, accepted/corrected | indirekt nur über neue korrigierte Revision | nein über NeuroForge; eigener read-only Agent-Endpunkt | nur über bestehende Agent-Policies + freigegebene KB |
|
||||
| Agent Web-Operator | indirekt sichtbar | explizit bestätigen/korrigieren | durch Korrektur | ja, authentifiziert/read-only | nicht durch Outcome allein |
|
||||
| NeuroForge Admin | technische Brain-Administration | technisch ja | technisch ja | nein | nein |
|
||||
| Control Center | Status/Konfiguration sichtbar | nein | nein | Verfügbarkeit sichtbar | nein |
|
||||
| Research/SearXNG | nein | Research-Evidence, nicht trusted outcome | nein | nein | nein |
|
||||
|
||||
`POST /api/v1/integrations/outcomes/search` akzeptiert den NeuroForge App-Key und liefert ausschließlich aktive Memories der serverseitig festgelegten Outcome-Provenance. Es ist kein generischer Memory-Search-Endpunkt und gewährt keine Admin-Funktionen.
|
||||
`POST /api/v1/integrations/outcomes/search` akzeptiert ausschließlich den NeuroForge Integration-Token oder Admin-Token und liefert ausschließlich aktive Memories der serverseitig festgelegten Outcome-Provenance. Es ist kein generischer Memory-Search-Endpunkt und gewährt keine Admin-Funktionen.
|
||||
|
||||
### v1.4 graph scopes
|
||||
|
||||
| Actor | Capability | Credential | Write authority |
|
||||
|---|---|---|---|
|
||||
| Control -> Agent | runs/evidence/learning graphs | `CONTROL_READ_TOKEN` | none |
|
||||
| Control -> NeuroForge | research/brain graph | app API key | none through graph endpoints |
|
||||
| Control -> NeuroForge | research/brain graph | `NEUROFORGE_CONTROL_READ_TOKEN` | none through graph endpoints |
|
||||
| Control -> embedded Engineering Graph | structural read | none/internal | none |
|
||||
| Optional Codebase Memory MCP | developer code analysis | local process / allowed root | none in platform |
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## Ergebnis der Prüfung
|
||||
|
||||
Die 110 Variablennamen der bisherigen Agent-Konfiguration werden im aktuellen v1.4.x-Agenten
|
||||
Die 110 Variablennamen der bisherigen Agent-Konfiguration werden im aktuellen v1.5.0-Agenten
|
||||
weiterhin verwendet. Das Problem lag nicht in entfernten Agent-Funktionen, sondern in der zu kurzen
|
||||
Top-Level-`.env.example` des Mega-Projekts: 86 dieser 110 bisherigen Variablen waren dort nicht
|
||||
explizit dokumentiert.
|
||||
@@ -20,7 +20,7 @@ Diese Werte sollten im Mega-Stack nicht zur Host-Konfiguration benutzt werden:
|
||||
| `KNOWLEDGE_DIR` | `/app/knowledge` | `KB_DATA_PATH` |
|
||||
| `OLLAMA_URL` | `http://ollama:11434` | Compose-Service `ollama` |
|
||||
| `NEUROFORGE_URL` | `http://neuroforge:8080` | Compose-Service `neuroforge` |
|
||||
| `NEUROFORGE_API_KEY` | aus `NEUROFORGE_APP_API_KEY` | `NEUROFORGE_APP_API_KEY` |
|
||||
| `NEUROFORGE_API_KEY` | aus `NEUROFORGE_INTEGRATION_TOKEN` | `NEUROFORGE_INTEGRATION_TOKEN` |
|
||||
| `BRAIN_ACTIVITY_URL` | NeuroForge Event API | intern verdrahtet |
|
||||
|
||||
Compose überschreibt `HTTP_ADDR` jetzt explizit. Dadurch kann eine alte Standalone-Konfiguration
|
||||
@@ -50,7 +50,7 @@ Diese Unterschiede sind nicht automatisch falsch, müssen aber bewusst entschied
|
||||
|
||||
Neu gegenüber der bisherigen Agent-Only-Konfiguration sind insbesondere:
|
||||
|
||||
- NeuroForge Admin/App/Worker/Metrics Tokens
|
||||
- getrennte NeuroForge Admin/App/Integration/Control-Read/Worker/Metrics Tokens
|
||||
- `KNOWLEDGE_VECTOR_BACKEND=local|dual|neuroforge`
|
||||
- NeuroForge Namespace/Search/Failure Policy
|
||||
- Controlled Learning
|
||||
@@ -60,7 +60,7 @@ Neu gegenüber der bisherigen Agent-Only-Konfiguration sind insbesondere:
|
||||
- getrennte Autonomy-Aktivierung
|
||||
- Knowledge Integration Token
|
||||
- scoped `CONTROL_READ_TOKEN`
|
||||
- Control Center / NeuroForge / Knowledge Host Ports
|
||||
- Control-Center-Basic-Auth sowie Control Center / NeuroForge / Knowledge Host Ports
|
||||
- optionale Codebase-Memory-UI
|
||||
|
||||
## Empfohlene Migration
|
||||
|
||||
+8
-4
@@ -1,4 +1,4 @@
|
||||
# Environment configuration (v1.4.x)
|
||||
# Environment configuration (v1.5.0)
|
||||
|
||||
The repository-level `.env.example` is the canonical configuration template for the Mega stack.
|
||||
It intentionally includes the complete GLPI Agent configuration plus NeuroForge, controlled-learning,
|
||||
@@ -14,8 +14,8 @@ The old variables are still supported, but container-internal values are now own
|
||||
- `KNOWLEDGE_DIR=/app/knowledge`
|
||||
- `OLLAMA_URL=http://ollama:11434`
|
||||
- `NEUROFORGE_URL=http://neuroforge:8080`
|
||||
- `NEUROFORGE_API_KEY` is derived from `NEUROFORGE_APP_API_KEY`
|
||||
- Brain-activity endpoints are wired internally by Compose
|
||||
- `NEUROFORGE_API_KEY` is derived from `NEUROFORGE_INTEGRATION_TOKEN`
|
||||
- Brain-activity endpoints are wired internally by Compose and use `NEUROFORGE_INTEGRATION_TOKEN`
|
||||
|
||||
The host-facing ports are configured separately with `AGENT_HOST_PORT`, `KNOWLEDGE_HOST_PORT`,
|
||||
`CONTROL_HOST_PORT`, `NEUROFORGE_HOST_PORT`, `OLLAMA_HOST_PORT` and `SEARXNG_HOST_PORT`.
|
||||
@@ -64,7 +64,7 @@ Never commit `.env`. The tracked file must remain `.env.example` only.
|
||||
If credentials were pasted into issue trackers, chats, CI logs, shell history or screenshots,
|
||||
rotate them before production use.
|
||||
|
||||
## Research → Knowledge Staging (v1.4.5+)
|
||||
## Research → Knowledge Staging (v1.5.0+)
|
||||
|
||||
The autonomous research bridge is controlled independently from Research and Goal Learning:
|
||||
|
||||
@@ -79,3 +79,7 @@ NEUROFORGE_KB_STAGING_MAX_EVIDENCE=12
|
||||
`NEUROFORGE_KB_STAGING_URL` and `NEUROFORGE_KB_STAGING_TOKEN` are container-internal values owned by the root Compose file. The token is derived from the existing `KB_INTEGRATION_TOKEN`; do not duplicate it under a second operator-managed secret name.
|
||||
|
||||
This bridge can only create/update **human-review staging**. The Knowledge service enforces `auto_reply=false` and does not expose production promotion through this integration token.
|
||||
|
||||
## Production secret isolation
|
||||
|
||||
The production Compose does not use `env_file`. Agent and Knowledge receive only explicit runtime variables. NeuroForge Admin/Worker/Metrics, Knowledge editor and Control Center credentials are therefore not broadly inherited by unrelated containers. Local source builds use the separate `docker-compose.dev.yml` override.
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# Go-Live Gate – v1.5.0
|
||||
|
||||
## Registry und Start
|
||||
|
||||
Auf dem Produktionshost wird **nicht gebaut**. Voraussetzung ist ein freigegebener, unveränderlicher `IMAGE_TAG` in `.env`.
|
||||
|
||||
```sh
|
||||
./scripts/preflight.sh
|
||||
docker compose pull
|
||||
docker compose up -d --remove-orphans
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
Alternativ führt `./scripts/go-live.sh` genau diesen Ablauf ohne `make` aus. `IMAGE_TAG=latest`, Placeholder-Secrets, wiederverwendete Trust-Boundary-Tokens, `build:` oder `env_file:` im Produktions-Compose brechen den Preflight ab.
|
||||
|
||||
## Pflicht-Smoke-Test auf dem echten Host
|
||||
|
||||
1. Ollama enthält Chat- **und** Embedding-Modell (`gemma3`/konfiguriert und `embeddinggemma`/konfiguriert); NeuroForge `/readyz` muss 200 liefern.
|
||||
2. Knowledge `/api/health` und Agent `/readyz` liefern 200; Control `/healthz` bleibt ohne Login erreichbar, alle Betriebs-/Graphseiten verlangen Control-Basic-Auth.
|
||||
3. Agent kann mit dem Integration-Token Knowledge-Integration/Outcome-Pfade nutzen; der Control-Read-Token kann diese Schreibpfade nicht nutzen.
|
||||
4. Einen Research-Goal manuell ausführen. Fortschritt und ein Staging-Draft müssen auch dann entstehen können, wenn `NEUROFORGE_GOAL_LEARNING_ENABLED=false` ist.
|
||||
5. Einen zweiten parallelen Cycle desselben Goals auslösen; er muss `409 Conflict` erhalten.
|
||||
6. Staging-Draft im Knowledge-Editor prüfen und promoten. Der Produktionsartikel erscheint genau einmal und der Draft wird archiviert.
|
||||
7. NeuroForge stoppen: Knowledge und Control müssen weiterlaufen; Agent verhält sich entsprechend `KNOWLEDGE_VECTOR_BACKEND`/`NEUROFORGE_FAIL_OPEN`.
|
||||
8. Vor GLPI-Schreibfreigabe einen vollständigen Ticketdurchlauf in `DRY_RUN=true` prüfen. Erst danach die gewünschten Automationen einzeln aktivieren.
|
||||
|
||||
Docker, eine echte GLPI-Instanz, SearXNG und Ollama stehen in der Build-/Review-Umgebung nicht zur Verfügung; dieser Host-Smoke-Test ist deshalb ein bewusstes externes Release-Gate und darf nicht als lokal bestanden markiert werden.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Migration v1.4.5 → v1.5.0
|
||||
|
||||
## 1. Back up v1.4.5 data
|
||||
|
||||
Take an existing host backup before replacing the checkout. For future v1.5.0 backups use `scripts/backup-data.sh`.
|
||||
|
||||
## 2. Replace/update configuration
|
||||
|
||||
Start from the v1.5.0 `.env.example`; do not simply keep the old broad Compose environment behavior. Preserve reviewed Agent/GLPI policy values and add:
|
||||
|
||||
```env
|
||||
IMAGE_TAG=1.5.0
|
||||
NEUROFORGE_INTEGRATION_TOKEN=<unique 24+ char secret>
|
||||
NEUROFORGE_CONTROL_READ_TOKEN=<unique 24+ char secret>
|
||||
CONTROL_BASIC_AUTH_USER=admin
|
||||
CONTROL_BASIC_AUTH_PASSWORD=<unique 12+ char password>
|
||||
NEUROFORGE_READINESS_OLLAMA_LIVE=true
|
||||
AGENT_LEGACY_KNOWLEDGE_EDITOR_ENABLED=false
|
||||
```
|
||||
|
||||
Keep the pre-existing Admin/App/Worker/Metrics, Knowledge integration and Agent Control-Read tokens unique. `./scripts/generate-secrets.sh` emits all required new secret values.
|
||||
|
||||
## 3. Understand credential remapping
|
||||
|
||||
- Agent `NEUROFORGE_API_KEY` and Brain Activity use `NEUROFORGE_INTEGRATION_TOKEN` internally.
|
||||
- Control Center uses `NEUROFORGE_CONTROL_READ_TOKEN` for NeuroForge and `CONTROL_READ_TOKEN` for Agent read-only endpoints.
|
||||
- The general `NEUROFORGE_APP_API_KEY` no longer authorizes `/api/v1/integrations/*` writes.
|
||||
|
||||
## 4. Deploy registry images only
|
||||
|
||||
```sh
|
||||
./scripts/preflight.sh
|
||||
docker compose pull
|
||||
docker compose up -d --remove-orphans
|
||||
```
|
||||
|
||||
Do not run a production source build. Local development uses:
|
||||
|
||||
```sh
|
||||
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
|
||||
```
|
||||
|
||||
## 5. Verify before enabling GLPI writes
|
||||
|
||||
Follow every gate in `docs/GO-LIVE-v1.5.0.md`. In particular verify both Ollama models, Research→Staging with goal-summary learning disabled, duplicate-cycle `409`, promotion, degraded NeuroForge behavior, and a complete `DRY_RUN=true` GLPI ticket flow.
|
||||
@@ -0,0 +1,34 @@
|
||||
# Validation – v1.5.0
|
||||
|
||||
This file records reproducible release gates. It deliberately distinguishes checks possible in the source-review environment from host-only Docker/GLPI checks.
|
||||
|
||||
## Locally executed
|
||||
|
||||
- Four Go modules: `go test ./...` — PASS.
|
||||
- Four Go modules: `go vet ./...` — PASS.
|
||||
- Four Go modules: `go build ./...` — PASS.
|
||||
- Targeted race suites: NeuroForge Store/Brain/HTTP API, Agent state/knowledge/learning/core agent, Knowledge Store/Staging/Server, Control — PASS.
|
||||
- NeuroForge live Ollama readiness regression: missing embedding model → 503; both configured models → 200 — PASS.
|
||||
- Goal per-ID single-flight regression — PASS.
|
||||
- Scoped-token trust-boundary regression — PASS.
|
||||
- Environment-managed Admin-secret mutation regression — PASS.
|
||||
- Knowledge browser same-origin regression — PASS.
|
||||
- Knowledge promotion rollback regression — PASS.
|
||||
- Control Center Basic Auth regression — PASS.
|
||||
- Production Compose static gate: no project `build:`, no `env_file:`, exact six registry image families with `${IMAGE_TAG}` — PASS.
|
||||
- Agent production environment secret-isolation check — PASS.
|
||||
- Shell syntax (`sh -n`) and `git diff --check` — PASS.
|
||||
- Engineering graph regeneration/idempotence — PASS.
|
||||
|
||||
## Host-only, still mandatory
|
||||
|
||||
The review environment does not provide Docker/Compose, GLPI, SearXNG or a production Ollama. Therefore the following are release-host gates rather than local PASS claims:
|
||||
|
||||
- authenticated registry pull of the final immutable tag;
|
||||
- `docker compose config`, `pull`, `up` and health state using the real `.env`;
|
||||
- real Ollama model inventory and inference;
|
||||
- GLPI read/write smoke flow;
|
||||
- optional SearXNG research flow;
|
||||
- backup/restore rehearsal against actual Docker volumes and host paths.
|
||||
|
||||
Use `scripts/preflight.sh`, `scripts/go-live.sh` and `docs/GO-LIVE-v1.5.0.md` on the target host.
|
||||
Reference in New Issue
Block a user