63 lines
7.1 KiB
Markdown
63 lines
7.1 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. Git URLs are metadata; the server does not fetch or clone them. 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.
|