caoimhinr 3bd431bea0 docs: update deploy notes — corvid pulled from Forgejo, no vendor/ bundling

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-25 19:39:39 +02:00

2.2 KiB

Raw Blame History

corvid

Standalone ticket-management service for AI agents. FastAPI + Postgres + MCP server.

Extracted from homelab-dashboard — the homelab-dashboard app continues to use corvid as a pip package (Option A integration).

Package

corvid/
  models.py    — Ticket, TicketAttachment, Base (SQLAlchemy ORM)
  router.py    — make_router(api_key, get_db, require_user=None) → APIRouter
  config.py    — DATABASE_URL, TICKETS_API_KEY env vars
  main.py      — standalone FastAPI app (no web UI)
  database.py  — engine, get_db
alembic/       — migration chain for standalone deployments
mcp_server.py  — FastMCP server; primary agent interface

MCP server

mcp_server.py is the centralized homelab MCP server. It exposes:

Ticket CRUD + attachments (via HOMEDASH_URL API)
Homelab system logs (/api/logs)

Configure in ~/.claude/mcp.json:

"homelab-tickets": {
  "command": "python3",
  "args": ["/home/caoimhinr/Projects/corvid/mcp_server.py"],
  "env": {
    "HOMEDASH_URL":   "https://homedash.welvaert.org",
    "HOMEDASH_API_KEY": "<TICKETS_API_KEY>"
  }
}

TICKETS_API_KEY value is in pve/ansible/host_vars/hetzner.yml (gitignored).

Standalone deployment

cp .env.example .env   # set DATABASE_URL and TICKETS_API_KEY
docker compose up -d

Default port: 8090 (maps to internal 8080).

homelab-dashboard integration

The dashboard depends on corvid via Forgejo:

# requirements.txt
corvid @ git+https://forgejo.welvaert.org/caoimhinr/corvid.git@main

Local dev: pip install -e ~/Projects/corvid

Push corvid to Forgejo before rebuilding the dashboard image — the Docker build pulls @main at build time. See homelab-dashboard/CLAUDE.md for the full deploy procedure.

Local dev

pip install -e ".[dev,mcp]"
TICKETS_API_KEY="" DATABASE_URL="sqlite+aiosqlite:///dev.db" \
  uvicorn corvid.main:app --reload --port 8090

DB migrations

Alembic runs at startup (entrypoint.sh). Add new migrations in alembic/versions/ following the NNNN_<slug>.py naming convention.

The dashboard keeps its own separate migration chain — corvid's migrations are only for fresh standalone deployments.

2.2 KiB Raw Blame History