# 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)