release 2026.07.07-24520d4

2026-07-07 13:46:12 +00:00
parent ecb8d90ce6
commit 37a853d12f
6 changed files with 674 additions and 0 deletions
@@ -0,0 +1,105 @@
+# EasyMCP / SapB1Mcp — Installation (Kunden-Deployment)
+
+Der Stack wird direkt aus der öffentlichen Registry von `git.kraemerweb.de`
+installiert und aktualisiert — es wird kein Installationspaket kopiert.
+
+## Voraussetzungen
+
+- Linux-Host, x86_64 (getestet: Debian 12/13)
+- Docker Engine ≥ 24 mit Compose-Plugin v2 (`docker compose version`)
+  — alternativ ein vorhandenes `docker-compose`-Binary
+- `curl`
+- **HTTPS-Zugriff auf `git.kraemerweb.de`** (Release-Dateien + Container-Registry)
+- Ein Reverse Proxy mit **TLS** (z. B. Caddy, nginx, Traefik) vor dem Stack.
+  HTTPS ist Pflicht: der MCP-Server validiert OAuth-Tokens nur gegen einen
+  HTTPS-Issuer.
+- Erreichbarer SAP Business One Service Layer (`https://<sap-host>:50000/b1s/`)
+
+## Installation
+
+1. **Setup-Skript holen** (z. B. nach `/opt/sapb1mcp`):
+
+   ```
+   mkdir -p /opt/sapb1mcp && cd /opt/sapb1mcp
+   curl -fsSLO https://git.kraemerweb.de/kraemerweb/easymcp-release/raw/branch/main/setup.sh
+   bash setup.sh
+   ```
+
+   `bash setup.sh <version>` installiert eine bestimmte Version (Tags siehe
+   Release-Repo); ohne Angabe wird `latest` verwendet. Das Skript lädt
+   `docker-compose.yml`, `hydra.yml` und `.env.example`, erzeugt
+   `secrets/creds_key` und eine `.env` mit fertigen Zufalls-Secrets.
+
+2. **`.env` anpassen** — Pflichtwerte:
+
+   | Variable | Bedeutung |
+   |---|---|
+   | `PUBLIC_ISSUER` | öffentliche HTTPS-URL des OAuth-Issuers (vHost → Port 4444) |
+   | `LOGIN_URL` | öffentliche HTTPS-URL des Login-Dienstes (vHost → Port 8081) |
+   | `MCP_RESOURCE_URL` | öffentliche HTTPS-URL des MCP-Servers (vHost → Port 8080) |
+   | `SL_BASE_URL` | SAP Service Layer, trailing `/b1s/` ist Pflicht |
+   | `SL_COMPANYDB` | SAP-Firmendatenbank |
+   | `ADMIN_SAP_USER` | SAP-Benutzer mit Zugang zum Admin-UI (Port 8082) |
+   | `MCP_ALLOWED_USERS` | SAP-Benutzer mit MCP-Dauerzugriff (Allowlist, default-deny) |
+
+   `PG_PASSWORD`, `SECRETS_SYSTEM`, `APP_VERSION` und `PROJECT_DIR` hat
+   `setup.sh` bereits gesetzt. `SL_INSECURE=true` nur bei self-signed
+   SAP-Zertifikat.
+
+3. **Stack starten:**
+
+   ```
+   docker compose pull
+   docker compose up -d
+   ```
+
+4. **Verifizieren:**
+
+   ```
+   docker compose ps                 # alle Dauerläufer "healthy"
+   curl -s http://127.0.0.1:8080/.well-known/oauth-protected-resource
+   ```
+
+## Reverse Proxy
+
+Alle Dienste binden per Default **nur an 127.0.0.1**. Läuft der Reverse Proxy
+auf einem anderen Host, in `.env` `BIND_ADDR`/`ADMIN_BIND` auf die interne
+Host-IP setzen — **nie 0.0.0.0**.
+
+| vHost (Beispiel) | Backend-Port | Dienst |
+|---|---|---|
+| `mcp.<domain>` | 8080 | MCP-Resource-Server |
+| `mcp-oauth.<domain>` | 4444 | Hydra (OAuth-Issuer) |
+| `mcp-login.<domain>` | 8081 | Login/Consent |
+| `mcp-admin.<domain>` (intern!) | 8082 | Admin-UI |
+
+Der Proxy muss `X-Forwarded-Proto: https` setzen (TLS-Terminierung).
+Das Admin-UI gehört NICHT ins öffentliche Internet.
+
+## Update auf eine neue Version
+
+**Weg 1 — über das Admin-UI (empfohlen):** Seite **Update** öffnen, optional
+eine Zielversion eintragen (leer = `latest`), „Update starten" klicken. Der
+Stack holt die neuen Images aus der Registry und erneuert alle Dienste selbst
+(`.env`, `secrets/` und die Datenbank bleiben erhalten). Dabei startet auch
+das Admin-UI neu — danach neu anmelden.
+
+**Weg 2 — manuell per SSH:**
+
+```
+bash setup.sh [version]   # aktualisiert Deployment-Dateien + APP_VERSION
+docker compose pull
+docker compose up -d
+```
+
+## Rollback
+
+Wie ein Update, nur mit einer älteren Versionsnummer als Zielversion
+(Admin-UI-Feld „Zielversion" bzw. `bash setup.sh <version>`).
+
+## Backup
+
+- Docker-Volume `sapb1mcp_pgdata` (Postgres: Benutzer, Audit, Hydra-Clients)
+- `secrets/creds_key` — ohne diese Datei sind gespeicherte SAP-Zugangsdaten
+  unwiederbringlich verloren
+- `.env` (enthält `SECRETS_SYSTEM` — nach Inbetriebnahme nie ändern)