easymcp-release/INSTALL.md

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)