Skip to content

Runbook: Azoth — operations

Field Value
Service Azoth
Owner Albert (IT)
Last verified 2026-07-17 — transcribed from the repo README + docs/DOCKER.md; not independently re-run by Athanor.

Purpose

Day-to-day operation of Azoth (the Outlook-attachments MCP): deploying, checking it's up, rotating the Entra client secret, and (re)registering the claude.ai connector.

Prerequisites

  • Access to the Ubuntu VM (ubuntuserver, 192.168.1.8) with Docker + Docker Compose.
  • An org-level self-hosted GitHub Actions runner on that VM labelled azoth (separate from Athanor's repo-scoped athanor-docs runner — Azoth is a different repo, so it needs an org-level runner with access to it).
  • Repo Actions secrets set on Alquemis-Automation/Azoth: M365_CLIENT_ID, M365_TENANT_ID, M365_CLIENT_SECRET.
  • For the Entra app / connector: Entra admin on the Azoth app registration and org-admin in claude.ai. Full registration steps live in the repo README.md (§1, §3).

Steps

Deploy a change (automated)

Push or merge to main on Alquemis-Automation/Azoth. The Deploy workflow runs on the self-hosted azoth runner and, on the VM: writes .env from the repo secrets, runs scripts/deploy.sh (docker compose up -d --build + waits for the container healthcheck), then deletes the workspace .env. workflow_dispatch is available for off-cycle runs.

Deploy manually (on the VM)

cd <repo>                       # the Azoth checkout on 192.168.1.8
# .env must exist with M365_CLIENT_ID / M365_TENANT_ID / M365_CLIENT_SECRET
bash scripts/deploy.sh          # build + up + healthcheck (idempotent)
docker compose logs -f outlook-mcp

Rotate the client secret

  1. Entra ID → the Azoth app registration → Certificates & secrets → new client secret; copy the Value.
  2. Update M365_CLIENT_SECRET in the repo's Actions secrets and in the claude.ai connector's advanced OAuth config (both must match the Entra app).
  3. Redeploy (push to main, or workflow_dispatch, or deploy.sh on the VM) so the container picks up the new secret.
  4. Confirm (below), then delete the old secret in Entra.

Verification

  • Container healthy: curl -s http://127.0.0.1:8091/healthz on the VM returns OK (unauthenticated; same check the container HEALTHCHECK uses).
  • Discovery endpoint answers: https://azoth.alquemis.com/.well-known/oauth-protected-resource returns the RFC 9728 JSON with the correct resource (…/mcp) and authorization_servers (the Entra issuer).
  • Auth gate works: https://azoth.alquemis.com/mcp without a token returns 401 + WWW-Authenticate.
  • End-to-end: a connected user in claude.ai can list their recent messages and read an attachment.

Rollback

  • Bad deploy: git revert on main and push (redeploys the previous image), or on the VM check out the previous commit and re-run scripts/deploy.sh.
  • Bad secret rotation: restore the previous (still-valid) M365_CLIENT_SECRET in the Actions secrets + claude.ai connector config and redeploy; don't delete the old Entra secret until the new one is confirmed.
  • Container wedged: docker compose restart outlook-mcp (or down then up -d --build) on the VM. The outlook-mcp-data volume (token cache + logs) persists across restarts.

Contacts

Albert (owner/author) — the Entra app registration, Grant admin consent, the central Caddy block + DNS for azoth.alquemis.com, and the org-level runner are all his to manage.