fabi/Schulcloud-MCP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Pull the server image on the Pi instead of building it

Browse Source 
The Pi now runs registry.mc02.dev/schulcloud-mcp. Its compose file `!reset`s
the build section docker-compose.yml declares, so no `docker compose` command
there can fall back to building (Compose 2.24 or later). SCHULCLOUD_MCP_TAG
pins a commit's image; unset, the Pi follows `latest`.

`npm run publish-image` publishes from a development machine. It builds only a
clean working tree, so a commit tag names exactly that commit's code, for amd64
and arm64, tagged `latest` and with the short commit id. On an x86 machine
arm64 builds under QEMU, which the script checks for and explains rather than
registering unasked.

PI.md logs in to the registry, pulls and starts instead of building, and
updates by publishing and pulling. Rehearsed in a scratch compose project: the
image came from the registry, `up -d --build` built nothing, and the server
came up healthy with its database and no published ports.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-09-16 21:26:44 +02:00
parent bac91303bf
commit bfccb3f343
7 changed files with 141 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/DEPLOYMENT.md
View File

@@ -38,12 +38,14 @@ this server's bearer check.
## First deploy
[PI.md](PI.md) steps 2–5: clone to `/opt/schulcloud-mcp`, write `.env` (the Pi's
[PI.md](PI.md) steps 1–5: log in to `registry.mc02.dev`, clone to
`/opt/schulcloud-mcp` for the compose files, write `.env` (the Pi's
`COMPOSE_FILE`, `CADDY_NETWORK` and `POSTGRES_PASSWORD`, generated secrets, the
first Schulcloud token), then:
```bash
docker compose up -d --build
docker compose pull
docker compose up -d
docker compose logs -f schulcloud-mcp
```
@@ -216,15 +218,44 @@ use stdio:
`MCP_AUTH_TOKEN` is irrelevant in stdio mode — there is no network listener.
## Publishing an image
The Pi never builds: `deploy/docker-compose.pi.yml` runs
`registry.mc02.dev/schulcloud-mcp` and removes the build section it would
otherwise inherit. Images are published from a development machine:
```bash
npm run publish-image
docker buildx imagetools inspect registry.mc02.dev/schulcloud-mcp:latest # lists linux/amd64 and linux/arm64
```
`scripts/publish-image.sh` refuses a working tree with uncommitted changes, so
a tag always names exactly the code of one commit. It builds for `linux/amd64`
and `linux/arm64` and pushes two tags: `latest`, and the short commit id. It
also labels the image with the full commit and the repository.
Two things the build machine needs:
- **arm64 emulation on an x86 machine.** The script checks for it and prints
the command that registers QEMU —
`docker run --privileged --rm tonistiigi/binfmt --install arm64` — which lasts
until the next reboot.
- **A multi-platform push.** Docker's containerd image store supports it
directly. Without that store, create a builder first with
`docker buildx create --use`.
## Updating
```bash
cd /opt/schulcloud-mcp && git pull
docker compose up -d --build
docker compose exec schulcloud-mcp node -e "1" # sanity
npm run probe # re-verify the API assumptions
npm run publish-image # on a development machine
cd /opt/schulcloud-mcp && git pull # on the Pi: compose files and docs
docker compose pull && docker compose up -d
npm run probe # on a development machine: re-verify the API assumptions
```
A `.env` that pins `SCHULCLOUD_MCP_TAG` needs the new commit id before the pull.
Setting the previous one rolls back.
## Operational notes
- **Restart policy** is `unless-stopped`; the container comes back after a

53
docs/PI.md
View File

@@ -4,6 +4,10 @@ A step-by-step guide from a Pi with Docker to a working claude.ai connector.
[DEPLOYMENT.md](DEPLOYMENT.md) explains *why* each piece is there; this page is
the order to do it in.
The Pi never builds the server. It pulls the image published to
`registry.mc02.dev`, built for arm64 and amd64 by `npm run publish-image` on a
development machine ([DEPLOYMENT.md](DEPLOYMENT.md#publishing-an-image)).
```
claude.ai ─┐ ┌──────────── Pi (home, always on) ─────────────┐
Claude Code├─HTTPS─▶ VPS ─TCP─▶ │ Caddy ─▶ schulcloud-mcp ─▶ schulcloud-thueringen.de
@@ -18,7 +22,8 @@ CLI ───────┘ (public IP, │ (TLS) └─ postgres (p
OS is plenty; put Docker's data on an SSD rather than the SD card if you can,
since Postgres and the file mirror (about 1.3 GB on the current account) write
to it.
- **Docker Engine with the Compose plugin** on the Pi.
- **Docker Engine with the Compose plugin**, Compose 2.24 or later, on the Pi.
- **A login for `registry.mc02.dev`**, where the image is published.
- **Caddy running in a container on the Pi**, serving ports 80 and 443. This
server joins its Docker network; it opens no port of its own.
- **The VPS**, with a public IPv4 address, forwarding TCP ports 80 and 443 to the
@@ -34,13 +39,16 @@ CLI ───────┘ (public IP, │ (TLS) └─ postgres (p
sudo apt update && sudo apt full-upgrade -y
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker "$USER" # then log out and back in
docker compose version
docker compose version # v2.24 or later
timedatectl # "System clock synchronized: yes"
docker login registry.mc02.dev
```
The clock matters: token expiry and TLS certificates are both judged by it.
The clock matters: token expiry and TLS certificates are both judged by it. The
login is needed to pull, not only to push; Docker keeps it in
`~/.docker/config.json`.
## 2. Get the code
## 2. Get the compose files
```bash
sudo mkdir -p /opt/schulcloud-mcp && sudo chown "$USER": /opt/schulcloud-mcp
@@ -48,7 +56,9 @@ git clone https://git.mc02.dev/fabi/Schulcloud-MCP.git /opt/schulcloud-mcp
cd /opt/schulcloud-mcp
```
Every command below runs in `/opt/schulcloud-mcp`.
Every command below runs in `/opt/schulcloud-mcp`. The checkout provides the
compose files, `.env.example` and the Caddy snippet; its source code is not built
here.
## 3. Configure
@@ -74,6 +84,7 @@ POSTGRES_PASSWORD=$(openssl rand -hex 24)
MCP_AUTH_TOKEN=$(openssl rand -hex 32)
MCP_PATH_SECRET=$(openssl rand -hex 32)
INDEX_PERSONAL_FILES=true
# SCHULCLOUD_MCP_TAG=latest
EOF
```
@@ -81,12 +92,13 @@ What those lines do:
| Setting | |
|---|---|
| `COMPOSE_FILE` | Makes every `docker compose` command here use [`deploy/docker-compose.pi.yml`](../deploy/docker-compose.pi.yml), which joins Caddy's network and wires up the database. It also keeps `docker-compose.override.yml` out — that one is for local development and would publish ports and switch the crawl timer off. |
| `COMPOSE_FILE` | Makes every `docker compose` command here use [`deploy/docker-compose.pi.yml`](../deploy/docker-compose.pi.yml), which runs the registry image — removing the build section, so nothing can be built here — joins Caddy's network and wires up the database. It also keeps `docker-compose.override.yml` out — that one is for local development and would publish ports and switch the crawl timer off. |
| `CADDY_NETWORK` | The network Caddy reaches this server on, by the name `schulcloud-mcp`. |
| `POSTGRES_PASSWORD` | The bundled Postgres, which sits on a private network with this server only. Hex, so it needs no escaping inside the connection URL. |
| `MCP_AUTH_TOKEN` | What Claude Code, the CLI and the `/token` page present. |
| `MCP_PATH_SECRET` | The secret path claude.ai uses until OAuth exists. |
| `INDEX_PERSONAL_FILES` | Also indexes your own files and handed-in work, including teachers' feedback. Optional. |
| `SCHULCLOUD_MCP_TAG` | Which published image to run. Unset means `latest`; a commit id such as `bac9130` pins it, so updates happen only when you change it. Optional. |
**Copy `MCP_AUTH_TOKEN` and `MCP_PATH_SECRET` into your password manager now** —
you need both again in step 9, and neither is ever printed by the server:
@@ -110,11 +122,15 @@ restart (step 11).
## 5. Start the server
```bash
docker compose up -d --build # the first build takes a few minutes on a Pi
docker compose pull # the published image, and Postgres
docker compose up -d
docker compose ps
docker compose logs -f schulcloud-mcp
```
Nothing is built on the Pi: `pull` fetches the arm64 variant of the image, and
with the Pi file in place no `docker compose` command can fall back to a build.
Expect, within a few seconds:
```
@@ -339,15 +355,24 @@ hours, say.
## Updating
A new version is published first, from a development machine:
`npm run publish-image` ([DEPLOYMENT.md](DEPLOYMENT.md#publishing-an-image)).
Then, on the Pi:
```bash
cd /opt/schulcloud-mcp
git pull
docker compose up -d --build
git pull # compose files and docs
docker compose pull # the newly published image
docker compose up -d
docker compose logs --tail 20 schulcloud-mcp
```
`COMPOSE_FILE` in `.env` keeps applying the Pi settings. A rebuild keeps the
database, the mirror and a replaced token, all of which live in volumes.
`COMPOSE_FILE` in `.env` keeps applying the Pi settings. Recreating the container
keeps the database, the mirror and a replaced token, all of which live in volumes.
With `SCHULCLOUD_MCP_TAG` pinned, set it to the new commit id before pulling.
Going back works the same way: set the previous commit id, then `pull` and
`up -d`.
## Backups
@@ -370,12 +395,18 @@ database, the mirror and a replaced token, all of which live in volumes.
| Caddy never obtains a certificate | Port 80 not forwarded, or DNS not yet pointing at the VPS | Step 7 |
| `network … declared as external, but could not be found` | Wrong `CADDY_NETWORK` | Step 3 |
| `required variable … is missing a value` | A line missing from `.env` | Step 3 |
| `unauthorized` or `pull access denied` from `docker compose pull` | Not logged in to the registry on the Pi | `docker login registry.mc02.dev` |
| `no matching manifest for linux/arm64` | The image was published for amd64 only | Publish again with `npm run publish-image`, which builds both |
| Compose rejects `!reset` in `deploy/docker-compose.pi.yml` | Compose older than 2.24 | Update Docker (step 1) |
| `EACCES` for `/data/state` or `/data/mirror` in the logs | A volume created by an old image, owned by root | `docker compose down`, `docker volume rm schulcloud-mcp_state` (or `_mirror`), `docker compose up -d` |
## Security checklist
- `.env` is mode 600 and in no unencrypted backup.
- `docker compose ps` shows no published ports for `schulcloud-mcp` or `schulcloud-mcp-db`.
- The registry login in `~/.docker/config.json` is only base64-encoded. Keep the
Pi user's home private, and use an account that may only pull if your
registry can issue one.
- The VPS forwards raw TCP and opens only 80, 443, 51820/udp and SSH.
- The secret path stays out of Caddy's access log — this prints a count, never
the secret: