gitea-actions
117 lines
4.3 KiB
Markdown
117 lines
4.3 KiB
Markdown
# 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.
|
|
|
|
`MCP_REQUIRED_SCOPE` bleibt im Regelfall **leer**: claude.ai und ChatGPT
|
|
gewähren den `mcp`-Scope im Consent nicht — mit gesetztem Wert enden deren
|
|
Tool-Calls mit 403. Nur setzen, wenn ausschließlich Clients zugreifen, die
|
|
den Scope explizit anfordern.
|
|
|
|
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)
|
|
|
|
## Support / Troubleshooting
|
|
|
|
Für Support-Mitarbeiter ohne Server-Zugang gibt es den separaten Leitfaden
|
|
[`SUPPORT.md`](SUPPORT.md) — Störungsdiagnose komplett über das
|
|
Admin-Webinterface, ohne Kommandozeile.
|