2026-10-20 19:10:00 +02:00
2026-10-15 20:38:02 +02:00
2026-10-20 14:17:46 +02:00
2026-10-15 20:38:02 +02:00
2026-10-20 19:10:00 +02:00
2026-10-20 19:10:00 +02:00
2026-10-20 19:17:55 +02:00
2026-10-20 19:10:00 +02:00
2026-10-12 20:49:13 +02:00
2026-10-20 14:17:46 +02:00
2026-10-20 19:10:00 +02:00
2026-10-12 20:49:13 +02:00
2026-10-12 20:49:13 +02:00
2026-10-20 19:10:00 +02:00
2026-10-12 20:49:13 +02:00

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

.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:

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. 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:

.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.

S
Description
No description provided
Readme
508 KiB
Languages
Python 60.6%
HTML 19.8%
JavaScript 14.9%
SCSS 3.8%
CSS 0.9%