221 lines
7.4 KiB
Markdown
221 lines
7.4 KiB
Markdown
# MCP Deployment Workflow — End-to-End Example
|
|
|
|
This shows the complete workflow for deploying a new container using MCP tools, with annotations explaining REDACTED_APP_PASSWORD and why.
|
|
|
|
**Example service:** Stirling PDF at `pdf.vish.gg` on Atlantis
|
|
|
|
---
|
|
|
|
## The Full Workflow
|
|
|
|
### 1. Check — Does it exist already?
|
|
|
|
```
|
|
MCP: list_containers(endpoint="atlantis", filter_name="stirling")
|
|
MCP: cloudflare_list_dns_records(filter_name="pdf")
|
|
```
|
|
|
|
**Why MCP:** Faster than SSH + docker ps. Gets both Docker state and DNS in parallel. Prevents deploying duplicates.
|
|
|
|
---
|
|
|
|
### 2. Write the compose file
|
|
|
|
```
|
|
Tool: Write → hosts/synology/atlantis/stirling-pdf.yaml
|
|
```
|
|
|
|
**Standard Atlantis paths:**
|
|
- Config: `/volume2/metadata/docker/<service>/`
|
|
- Media: `/volume1/data/media/<type>/`
|
|
- Port: pick an unused one (check `list_containers` to see what's taken)
|
|
|
|
**Key things to include:**
|
|
- `restart: unless-stopped`
|
|
- `security_opt: no-new-privileges:true`
|
|
- LAN DNS servers if the service needs to resolve internal hostnames:
|
|
```yaml
|
|
dns:
|
|
- 192.168.0.200
|
|
- 192.168.0.250
|
|
```
|
|
|
|
---
|
|
|
|
### 3. Create DNS record
|
|
|
|
```
|
|
MCP: cloudflare_create_dns_record(name="pdf", content="184.23.52.14", proxied=True)
|
|
```
|
|
|
|
**Why MCP:** Single call — no need to know the zone ID or handle auth.
|
|
|
|
**Decision — proxied or not?**
|
|
- `proxied=True` (default): for web services — Cloudflare handles DDoS, caching, SSL at edge
|
|
- `proxied=False`: for Matrix federation, Headscale, DERP relays, TURN — these need direct IP access
|
|
|
|
**If proxied=True:** Uses the wildcard CF Origin cert (npm-8) in NPM — no new cert needed.
|
|
**If proxied=False:** Needs a real LE cert. Issue via certbot on matrix-ubuntu, add as new `npm-N`.
|
|
|
|
---
|
|
|
|
### 4. Check AdGuard — will LAN DNS resolve correctly?
|
|
|
|
```
|
|
MCP: adguard_list_rewrites()
|
|
```
|
|
|
|
Look for the `*.vish.gg → 100.85.21.51` wildcard. This resolves to matrix-ubuntu (`192.168.0.154`) which is where NPM runs — so for most `*.vish.gg` services this is **correct** and no extra rewrite is needed.
|
|
|
|
**Add a rewrite only if:**
|
|
- The service needs to bypass the wildcard (e.g. `pt.vish.gg → 192.168.0.154` was needed because the wildcard mapped to the Tailscale IP, not LAN IP)
|
|
- Internal services (Portainer, Atlantis) need to reach this domain and the wildcard points somewhere they can't reach
|
|
|
|
```
|
|
MCP: adguard_add_rewrite(domain="pdf.vish.gg", answer="192.168.0.154") # only if needed
|
|
```
|
|
|
|
---
|
|
|
|
### 5. Create NPM proxy host
|
|
|
|
No MCP tool yet for creating proxy hosts — use bash:
|
|
|
|
```bash
|
|
NPM_TOKEN=$(curl -s -X POST "http://192.168.0.154:81/api/tokens" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"identity":"your-email@example.com","secret":"..."}' | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")
|
|
|
|
curl -s -X POST "http://192.168.0.154:81/api/nginx/proxy-hosts" \
|
|
-H "Authorization: Bearer $NPM_TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"domain_names": ["pdf.vish.gg"],
|
|
"forward_scheme": "http",
|
|
"forward_host": "192.168.0.200", # Atlantis LAN IP
|
|
"forward_port": 7340,
|
|
"certificate_id": 8, # npm-8 = *.vish.gg CF Origin (for proxied domains)
|
|
"ssl_forced": true,
|
|
"allow_websocket_upgrade": true,
|
|
"block_exploits": true,
|
|
"locations": []
|
|
}'
|
|
```
|
|
|
|
**Cert selection:**
|
|
- Proxied `*.vish.gg` → cert `8` (CF Origin wildcard)
|
|
- Unproxied `mx.vish.gg` → cert `6` (LE)
|
|
- Unproxied `sso.vish.gg` → cert `12` (LE)
|
|
- See `docs/admin/mcp-server.md` for full cert table
|
|
|
|
**After creating**, verify with:
|
|
```
|
|
MCP: npm_get_proxy_host(host_id=<id>) # check nginx_err is None
|
|
MCP: npm_list_proxy_hosts(filter_domain="pdf.vish.gg")
|
|
```
|
|
|
|
---
|
|
|
|
### 6. Create data directories on the host
|
|
|
|
```
|
|
MCP: ssh_exec(host="atlantis", command="mkdir -p /volume2/metadata/docker/stirling-pdf/configs /volume2/metadata/docker/stirling-pdf/logs")
|
|
```
|
|
|
|
**Why before deploy:** Portainer fails with a bind mount error if the host directory doesn't exist. Always create dirs first.
|
|
|
|
---
|
|
|
|
### 7. Commit and push to Git
|
|
|
|
```bash
|
|
git add hosts/synology/atlantis/stirling-pdf.yaml
|
|
git commit -m "feat: add Stirling PDF to Atlantis (pdf.vish.gg)"
|
|
git push
|
|
```
|
|
|
|
**Why Git first:** Portainer pulls from Git. The file must be in the repo before you create the stack, or Portainer can't find it.
|
|
|
|
---
|
|
|
|
### 8. Deploy via Portainer API
|
|
|
|
```bash
|
|
curl -X POST "http://100.83.230.112:10000/api/stacks/create/standalone/repository?endpointId=2" \
|
|
-H "X-API-Key: <token>" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"name": "stirling-pdf-stack",
|
|
"repositoryURL": "https://git.vish.gg/Vish/homelab.git",
|
|
"repositoryReferenceName": "refs/heads/main",
|
|
"composeFile": "hosts/synology/atlantis/stirling-pdf.yaml",
|
|
"repositoryAuthentication": true,
|
|
"repositoryUsername": "Vish",
|
|
"repositoryPassword": "<gitea-token>",
|
|
"autoUpdate": {"interval": "5m"}
|
|
}'
|
|
```
|
|
|
|
**Notes:**
|
|
- `endpointId=2` = Atlantis. Use `list_endpoints` to find others.
|
|
- `autoUpdate: "5m"` = Portainer polls Git every 5 min and redeploys on changes — this is GitOps.
|
|
- The API call often times out (Portainer pulls image + starts container) but the stack is created. Check with `list_stacks` after.
|
|
|
|
**Alternatively:** Just add the file to Git and wait — if the stack already exists in Portainer with `autoUpdate`, it will pick it up automatically within 5 minutes.
|
|
|
|
---
|
|
|
|
### 9. Verify
|
|
|
|
```
|
|
MCP: list_containers(endpoint="atlantis", filter_name="stirling") → running ✓
|
|
MCP: check_url(url="https://pdf.vish.gg") → 200 or 401 ✓
|
|
MCP: get_container_logs(container_id="stirling-pdf", endpoint="atlantis") → no errors ✓
|
|
```
|
|
|
|
---
|
|
|
|
### 10. Add Uptime Kuma monitor
|
|
|
|
```
|
|
MCP: kuma_list_groups() → find Atlantis group (ID: 4)
|
|
MCP: kuma_add_monitor(
|
|
name="Stirling PDF",
|
|
monitor_type="http",
|
|
url="https://pdf.vish.gg",
|
|
parent_id=4,
|
|
interval=60
|
|
)
|
|
MCP: kuma_restart() → required to activate
|
|
```
|
|
|
|
---
|
|
|
|
## What MCP Replaced
|
|
|
|
| Step | Without MCP | With MCP |
|
|
|------|------------|----------|
|
|
| Check if running | `ssh atlantis "sudo /usr/local/bin/docker ps \| grep stirling"` | `list_containers(endpoint="atlantis", filter_name="stirling")` |
|
|
| Create DNS | Get CF zone ID → curl with bearer token → parse response | `cloudflare_create_dns_record(name="pdf", content="184.23.52.14")` |
|
|
| Check DNS overrides | SSH to Calypso → docker exec AdGuard → cat YAML → grep | `adguard_list_rewrites()` |
|
|
| Verify proxy host | Login to NPM UI at 192.168.0.154:81 → navigate to hosts | `npm_get_proxy_host(host_id=50)` |
|
|
| Check container logs | `ssh atlantis "sudo /usr/local/bin/docker logs stirling-pdf --tail 20"` | `get_container_logs(container_id="stirling-pdf", endpoint="atlantis")` |
|
|
| Add monitor | SSH to pi-5 → docker exec sqlite3 → SQL INSERT → docker restart | `kuma_add_monitor(...)` + `kuma_restart()` |
|
|
|
|
---
|
|
|
|
## Common Pitfalls
|
|
|
|
| Pitfall | Prevention |
|
|
|---------|------------|
|
|
| Bind mount fails — host dir doesn't exist | `ssh_exec` to create dirs **before** deploying |
|
|
| Portainer API times out | Normal — check `list_stacks` after 30s |
|
|
| 502 after deploy | Container still starting — check logs, wait 10-15s |
|
|
| DNS resolves to wrong IP | Check `adguard_list_rewrites` — wildcard may interfere |
|
|
| Wrong cert on proxy host | Check `npm_list_certs` — never reuse an existing `npm-N` |
|
|
| Stack not redeploying on push | Check Portainer `autoUpdate` is set on the stack |
|
|
|
|
---
|
|
|
|
**Last updated:** 2026-03-21
|