docs: add internal deployment guide, remove temp debug files
All checks were successful
Build and Push Monarch MCP Docker Image / build (push) Successful in 11s
All checks were successful
Build and Push Monarch MCP Docker Image / build (push) Successful in 11s
- Delete BUG-REPORT.md (bug resolved) - Delete MonarchAPI.md (research complete, library chosen) - Add .deployment.md with Komodo stack ops, auth notes, and troubleshooting
This commit is contained in:
207
.deployment.md
Normal file
207
.deployment.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# Monarch MCP Custom — Deployment Guide
|
||||
|
||||
> **Internal / Private.** Not for public distribution. This doc covers how the local Komodo deployment works and how to operate it.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Git push to main
|
||||
|
|
||||
v
|
||||
Gitea Actions (.gitea/workflows/build.yaml)
|
||||
|
|
||||
v
|
||||
Docker build + push to gitea.ext.ben.io/b3nw/monarch-mcp-custom:latest
|
||||
|
|
||||
v
|
||||
Komodo Stack "monarch-mcp" pulls image and deploys
|
||||
|
|
||||
v
|
||||
Container runs on host port 8070 (mapped to container 8000)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Gitea Build Workflow
|
||||
|
||||
**File:** `.gitea/workflows/build.yaml`
|
||||
|
||||
Triggers on every push to `main` or `master`:
|
||||
|
||||
1. Checks out the repo
|
||||
2. Logs into `gitea.ext.ben.io` container registry (uses `secrets.CR_PAT`)
|
||||
3. Builds and pushes `gitea.ext.ben.io/b3nw/monarch-mcp-custom:latest`
|
||||
|
||||
### Manual Build Trigger
|
||||
|
||||
If you need to force a rebuild without a code change, push an empty commit:
|
||||
|
||||
```bash
|
||||
git commit --allow-empty -m "chore: trigger rebuild"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
Or edit `.gitea/workflows/build.yaml` and push.
|
||||
|
||||
---
|
||||
|
||||
## Komodo Stack Deployment
|
||||
|
||||
**Stack Name:** `monarch-mcp`
|
||||
**Server:** `6942f06939bbe4eb5a9f21aa` (main Docker host)
|
||||
**Image:** `gitea.ext.ben.io/b3nw/monarch-mcp-custom:latest`
|
||||
**Host Port:** `8070` → Container `8000`
|
||||
|
||||
### Environment Variables (from `.env`)
|
||||
|
||||
| Variable | Purpose | Source |
|
||||
|---|---|---|
|
||||
| `MONARCH_TOKEN` | Session token for Monarch Money API | Extract from browser DevTools |
|
||||
| `MONARCH_EMAIL` | Account email for re-auth fallback | Plaintext |
|
||||
| `MONARCH_PASSWORD` | Account password for re-auth fallback | Plaintext |
|
||||
| `MONARCH_MFA_SECRET` | TOTP secret for re-auth fallback | Plaintext (from 2FA setup) |
|
||||
| `MONARCH_PORT` | Host port mapping (default 8070) | `.env` |
|
||||
| `LOG_LEVEL` | Python logging level (INFO/DEBUG) | `.env` |
|
||||
|
||||
### How to Redeploy
|
||||
|
||||
**Via Komodo UI:**
|
||||
1. Navigate to Stacks → monarch-mcp
|
||||
2. Click **Deploy** (or **Pull** then **Deploy** to force fresh image)
|
||||
|
||||
**Via MCP / API:**
|
||||
```python
|
||||
# Using the komodo_mcp tool
|
||||
DeployStack(stack="monarch-mcp")
|
||||
```
|
||||
|
||||
**Force fresh image pull:**
|
||||
The stack has `auto_pull: true`, so a standard Deploy should pull the latest image. If not, use **Pull Stack** first.
|
||||
|
||||
---
|
||||
|
||||
## Container Operations
|
||||
|
||||
### Check Logs
|
||||
|
||||
**Via Komodo UI:**
|
||||
Stack → monarch-mcp → Logs → Select service `monarch-mcp`
|
||||
|
||||
**Via Komodo API:**
|
||||
```python
|
||||
GetStackLog(stack="monarch-mcp", services=["monarch-mcp"], tail=50)
|
||||
```
|
||||
|
||||
### Health Check
|
||||
|
||||
The container exposes a health endpoint:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8070/health
|
||||
# Expected: {"status": "ok"}
|
||||
```
|
||||
|
||||
Docker compose healthcheck config (in `compose.yaml`):
|
||||
- Interval: 30s
|
||||
- Timeout: 10s
|
||||
- Retries: 3
|
||||
- Start period: 10s
|
||||
|
||||
---
|
||||
|
||||
## Local Development
|
||||
|
||||
### Install Dependencies
|
||||
|
||||
```bash
|
||||
uv sync
|
||||
```
|
||||
|
||||
### Run Locally
|
||||
|
||||
```bash
|
||||
uv run python src/monarch_mcp_custom/server.py
|
||||
# or
|
||||
python -m monarch_mcp_custom.server
|
||||
```
|
||||
|
||||
### Test the Library Directly
|
||||
|
||||
```bash
|
||||
uv run python -c "
|
||||
from monarchmoney import MonarchMoney, MonarchMoneyEndpoints
|
||||
print(MonarchMoneyEndpoints.BASE_URL)
|
||||
"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Authentication Notes
|
||||
|
||||
### Token Source
|
||||
The `MONARCH_TOKEN` is a session token extracted from browser DevTools:
|
||||
1. Log into Monarch Money at `https://app.monarch.com`
|
||||
2. Open DevTools → Network → filter by `graphql`
|
||||
3. Click any request → Headers → `Authorization: Token <value>`
|
||||
4. Copy the token value (without `Token ` prefix)
|
||||
|
||||
### Token Lifetime
|
||||
Tokens appear to last several months. If API calls start returning 401:
|
||||
1. Extract a fresh token from the browser
|
||||
2. Update the `MONARCH_TOKEN` env var in Komodo
|
||||
3. Redeploy the stack
|
||||
|
||||
### Re-Authentication Fallback
|
||||
If token auth fails, the MCP server will attempt to re-authenticate using `MONARCH_EMAIL`, `MONARCH_PASSWORD`, and `MONARCH_MFA_SECRET`. This is subject to rate limiting by Monarch.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 401 Unauthorized
|
||||
- Token expired? Extract fresh token from browser.
|
||||
- Check `MONARCH_TOKEN` is set correctly in Komodo stack env.
|
||||
- Verify library version in startup logs (should show `monarchmoney 1.3.2+` and `BASE_URL: https://api.monarch.com`).
|
||||
|
||||
### 429 Rate Limited
|
||||
- Monarch Money rate-limits login attempts.
|
||||
- Wait ~15-60 seconds before retrying.
|
||||
- The retry decorator handles 429 with a 15s backoff.
|
||||
|
||||
### Image Not Updating
|
||||
- Check Gitea Actions for build failures.
|
||||
- Force a **Pull Stack** in Komodo before deploying.
|
||||
- Verify the commit hash in Komodo matches the latest.
|
||||
|
||||
### Build Fails
|
||||
- Check `.gitea/workflows/build.yaml` logs in Gitea.
|
||||
- Ensure `secrets.CR_PAT` is valid for `gitea.ext.ben.io`.
|
||||
|
||||
---
|
||||
|
||||
## Useful Commands
|
||||
|
||||
```bash
|
||||
# Quick health check
|
||||
curl -s http://localhost:8070/health | jq .
|
||||
|
||||
# Check running container
|
||||
docker ps | grep monarch-mcp
|
||||
|
||||
# Inspect container logs directly on host
|
||||
docker logs monarch-mcp-custom --tail 50 -f
|
||||
|
||||
# Restart container
|
||||
docker restart monarch-mcp-custom
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Resources
|
||||
|
||||
- **Repo:** `git.local.ben.io:b3nw/monarch-mcp-custom.git`
|
||||
- **Container Registry:** `gitea.ext.ben.io/b3nw/monarch-mcp-custom`
|
||||
- **Komodo Stack:** `monarch-mcp` (ID: `694b492b6e2254e6ad636e9b`)
|
||||
- **Upstream Library:** https://github.com/bradleyseanf/monarchmoneycommunity
|
||||
Reference in New Issue
Block a user