Files
2026-10-21 15:25:33 +02:00

67 lines
7.6 KiB
Markdown

# Common Ground dashboard and projects
Django dashboard with an authenticated project manager, Kanban boards, Markdown specifications, and a separate Streamable HTTP MCP server. The original Today, Health, Energy, Home, and Showcase page templates remain in place.
## Local setup
```sh
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python manage.py migrate
.venv/bin/python manage.py createsuperuser
npm install
npm run dev
```
The dashboard runs at `http://127.0.0.1:8765/`. `npm run dev` uses the existing package scripts; `npm run dev:mcp` starts the MCP process at `http://127.0.0.1:8766/mcp`. If Node.js is unavailable, use `.venv/bin/uvicorn mcp_server.server:app --host 127.0.0.1 --port 8766`. Port 8766 is separate from TasksNest's MCP listener.
### Persistent local services
This host runs systemd with Python 3.12, while the development shell's `.venv` uses Python 3.13. The user services in `deploy/systemd/` therefore use the project-local `.venv-host`. To recreate it on the host, run `python3 -m venv .venv-host` and `.venv-host/bin/python -m pip install -r requirements.txt` there. Keep both virtualenvs out of Git.
The linked `common-ground-django.service` and `common-ground-mcp.service` start on login or boot through the systemd user manager. The local Django service binds to `127.0.0.1:8765`; MCP binds only to the host's Tailscale address, `100.91.62.59:8766`. Manage them with:
```sh
systemctl --user status common-ground-django.service common-ground-mcp.service
systemctl --user restart common-ground-django.service common-ground-mcp.service
journalctl --user -u common-ground-mcp.service -f
```
If running these commands from the Codex Flatpak shell, prefix them with `flatpak-spawn --host` so they reach the host's systemd user manager. For example: `flatpak-spawn --host systemctl --user restart common-ground-mcp.service`.
The Django process on port 8765 provides a local dashboard and OAuth server. The public Caddy configuration currently forwards the dashboard and OAuth routes to a separate Django process at `100.91.62.59:2345`, and MCP routes to `100.91.62.59:8766`. An unauthenticated `GET /mcp` should return HTTP 401. Optional settings for the user services belong in `~/.config/common-ground/env`, outside the repository. After changing that file, restart the affected service.
Remote clients use the public HTTPS reverse proxy. Route `/mcp` and `/.well-known/oauth-protected-resource/mcp` to the Tailscale-only MCP listener on port 8766, and the dashboard plus OAuth discovery and `/o/` to the Django process on port 2345. The processes must share the same database and `DJANGO_SECRET_KEY`. Keep MCP off public and LAN interfaces; the Tailscale address is reachable through the authenticated tailnet.
For `https://projects.jorendegraaf.eu`, MCP advertises `MCP_PUBLIC_URL=https://projects.jorendegraaf.eu/mcp` and `OAUTH_ISSUER_URL=https://projects.jorendegraaf.eu`. Set these in the public Django process too, especially to make its Profile configuration check agree. Profile shows the visiting HTTPS origin plus `/mcp`; on localhost it retains the separate development port. OAuth discovery, protected-resource metadata, and the reverse proxy must agree on the public URLs before a remote client can connect. Redirect the singular `project.jorendegraaf.eu` alias to the canonical plural hostname so OAuth resource identifiers remain consistent. Keep `DJANGO_ALLOWED_HOSTS` restricted to served hostnames. Caddy forwards the original `Host` and `X-Forwarded-Proto` headers by default.
`/projects/` contains active and archived projects. New projects seed editable To-do, In Progress, and Done columns. New cards use the board's selected default column and Medium priority. Cards store raw Markdown, a revision history, explicit blockers, comments, and activity. HTML output is sanitized. The project's Git URL also powers a read-only documentation index with sanitized browsing and MCP retrieval; see [Git-first documentation setup and operations](docs/git-documentation.md). Profile timezone accepts an IANA name and controls timestamps on authenticated pages; the default is Europe/Amsterdam.
## OAuth and MCP
The Django server hosts OAuth authorization, token, revocation, and discovery endpoints under `/o/` and `/.well-known/oauth-authorization-server`. The MCP process hosts `/mcp` and `/.well-known/oauth-protected-resource/mcp`. Reads require `projects:read`, and writes require `projects:write`. OAuth authorization codes require PKCE. Tokens expire after one hour, can be revoked from Profile, and are stored hashed by django-oauth-toolkit. After deploying new MCP tools, restart the MCP service and refresh its ChatGPT plugin connection so the updated tool list appears.
Authenticated dynamic client registration is enabled at `/o/register/`. A signed-in user can register a client; session requests also need a CSRF token. Anonymous registration is denied. You can also create a public authorization-code client in Django admin, setting its exact HTTPS redirect URI and the needed scopes. Profile shows active grants and revocation controls.
For ChatGPT's custom MCP plugin, open Advanced OAuth settings and choose a provided/registered client rather than dynamic registration. Use the public authorization-code client registered with redirect URI `https://chatgpt.com/connector_platform_oauth_redirect`, token endpoint authentication method `none`, and default scope `projects:read` (add `projects:write` to enable edits). The server URL is `https://projects.jorendegraaf.eu/mcp`; the authorization and token endpoints are `https://projects.jorendegraaf.eu/o/authorize/` and `https://projects.jorendegraaf.eu/o/token/`. The protected-resource metadata's authorization server must exactly match the OAuth discovery issuer, including its trailing slash.
Local accounts work by default. To enable separate OIDC sign-in to the dashboard, set `OIDC_OP_ISSUER`, `OIDC_OP_AUTHORIZATION_ENDPOINT`, `OIDC_OP_TOKEN_ENDPOINT`, `OIDC_OP_USER_ENDPOINT`, `OIDC_OP_JWKS_ENDPOINT`, `OIDC_RP_CLIENT_ID`, and `OIDC_RP_CLIENT_SECRET`. Register `/oidc/callback/` at the provider. OIDC identities are linked by verified issuer and subject; a matching email does not link an existing local account. The actual provider callback still needs an integration test with your provider configuration.
Set `MCP_PUBLIC_URL` and `OAUTH_ISSUER_URL` to the public HTTPS MCP endpoint and Django origin. Route `/mcp` and `/.well-known/oauth-protected-resource/mcp` to port 8766, and OAuth routes to the Django process. Preserve the Authorization header. The MCP process and Django must use the same database and `DJANGO_SECRET_KEY`.
## Deployment settings
Set `DJANGO_DEBUG=0`, a strong `DJANGO_SECRET_KEY`, `DJANGO_ALLOWED_HOSTS`, `MCP_PUBLIC_URL`, and `OAUTH_ISSUER_URL`. `DJANGO_CSRF_TRUSTED_ORIGINS` accepts a comma-separated origin list if needed behind a proxy. Production mode requires HTTPS URLs and enables secure cookies, SSL redirect, and HSTS. The local sign-in throttle uses Django's process-local cache; use a shared cache when running multiple workers.
Run checks and tests with:
```sh
.venv/bin/python manage.py check
.venv/bin/python manage.py test projects
```
For compiled frontend assets, run `npm run build`. Django uses Vite in development, the build manifest when present, and checked-in preview assets otherwise.
## Knowledge Library
`/knowledge/` is a separate personal link library with its own menu, data and capture API. It does not use Project Manager cards. See [Knowledge Library setup and limitations](docs/knowledge-library.md) and the [Pocket source review](docs/research/knowledge-library-pocket.md). The separate MCP `knowledge:read` scope grants contextual discovery; opt-in ntfy scheduling is available through a management command.