Live Deployment Runbook

Live Deployment Runbook

This page is a short operator reminder for the current www.arleo.eu / mcp.arleo.eu deployment. It is intentionally practical and should not contain secrets.

Host Responsibilities

Hostname	Role
www.arleo.eu	Hugo public site and static AgentReady discovery files
mcp.arleo.eu	MCP Streamable HTTP endpoint and OAuth issuer

Expected traffic path:

Cloudflare
  -> host OpenResty
    -> www.arleo.eu -> Hugo VM Nginx -> Hugo static files
    -> mcp.arleo.eu -> Hugo VM mcp-hugo-server-go service on port 8088

Important Paths

Repository-side reference examples:

docs/examples/agent-ready/openresty-www.arleo.eu.conf
docs/examples/agent-ready/openresty-mcp.arleo.eu.conf
docs/examples/agent-ready/nginx-hugo-vm.conf
docs/examples/agent-ready/static/auth.md
docs/examples/agent-ready/static/.well-known/oauth-protected-resource
docs/examples/agent-ready/static/llms.txt
docs/examples/agent-ready/static/robots.txt

Live host paths to check before changing code:

/etc/openresty/sites-enabled/www.arleo.eu
/etc/openresty/sites-enabled/mcp.arleo.eu
/etc/mcp-hugo-server-go/config.yaml
/etc/mcp-hugo-server-go/oauth-clients.yaml
/etc/systemd/system/mcp-hugo-server-go.service

Hugo VM paths:

/home/jm/hugo-site/static/
/home/jm/hugo-site/static/auth.md
/home/jm/hugo-site/static/.well-known/
/var/www/hugo
/etc/nginx/sites-available/hugo

Deployment Commands

Build and deploy the Go server from the repository:

bash deploy/deploy.sh

Then verify the service on the VM:

ssh hugo-vm 'systemctl status mcp-hugo-server-go --no-pager'
ssh hugo-vm 'journalctl -u mcp-hugo-server-go -n 80 --no-pager'

Rebuild Hugo static output after editing Hugo static files:

ssh hugo-vm 'sudo -u hugo-mcp sh -lc "cd /home/jm/hugo-site && hugo --destination /var/www/hugo --cleanDestinationDir"'

Before relying on that command, validate the real permissions:

ssh hugo-vm 'id hugo-mcp'
ssh hugo-vm 'stat -c "%U:%G %a %n" /home/jm/hugo-site/static /home/jm/hugo-site/public /var/www/hugo'

If rebuild fails with a filesystem error such as chtimes ... operation not permitted, stop and fix ownership or publish the exact changed static files intentionally. Do not report the build as successful.

This can also happen through the MCP server's own build_site tool, running as a different system user (mcp-hugo-server-go, not hugo-mcp) — see AgentReady Pitfalls § "A second, distinct cause of the same error" (#521) for that specific diagnosis path, which is not fixed by the ReadWritePaths check the tool's own error message suggests.

Live Verification

curl -skD - https://www.arleo.eu/auth.md -o /tmp/www-auth.md
curl -skD - https://mcp.arleo.eu/auth.md -o /tmp/mcp-auth.md
curl -sk https://mcp.arleo.eu/.well-known/oauth-authorization-server | jq .
curl -sk https://mcp.arleo.eu/.well-known/oauth-protected-resource | jq .
curl -sk https://mcp.arleo.eu/.well-known/mcp/server-card.json | jq .
SMOKE_LIVE=1 ./scripts/check-agent-ready.sh
SMOKE_LIVE=1 ./scripts/smoke-agent-interop.sh

Cloudflare Cache

If the VM and origin are correct but live output is stale, purge only the affected public URLs.

Never print Cloudflare tokens or API responses containing secrets in logs, issues, wiki pages, CI output, or screenshots.

Common Mistake

Do not debug only the Go process when www.arleo.eu/auth.md is wrong. That file can be served by the Hugo static site through OpenResty and Nginx. Check the Hugo VM source file first.

Also do not keep backup vhost files inside the active OpenResty include path. sites-enabled/* treats *.bak files as live configuration if they remain in that directory.