merge: align dev branch with main

2026-06-03 08:51:02 +00:00
parent 51a399c775
commit b39d6ce5f4
319 changed files with 30221 additions and 9221 deletions
@@ -0,0 +1,31 @@
+## Why
+
+The current approach of proxying tool instances through the backend API is fragile and creates a bottleneck. Every HTTP request and WebSocket connection to a tool instance (code-server, jupyter, etc.) must pass through the FastAPI application, adding latency and consuming API resources. Cloudflare Tunnel provides a robust alternative: each instance gets its own public subdomain with automatic HTTPS, without exposing ports or requiring complex reverse proxy rules.
+
+## What Changes
+
+- Replace the API proxy endpoint (`/instances/{id}/proxy/`) with Cloudflare Tunnel integration
+- Run a `cloudflared` container alongside the API that manages tunnels programmatically via the Cloudflare API
+- When a tool instance starts, create a unique Cloudflare Tunnel and DNS record pointing to the instance's internal container name and port
+- Store the public URL (e.g., `https://instance-abc123.headquarter.commumedia.org`) in the ToolInstance model
+- Update the frontend "Open" button to use the Cloudflare URL instead of the proxy path
+- Remove the proxy endpoint and related code (instance_proxy.py)
+- **BREAKING**: The `/instances/{id}/proxy/{path:path}` endpoint will be removed
+
+## Capabilities
+
+### New Capabilities
+
+- `cloudflare-tunnel-management`: Creating, deleting, and managing Cloudflare tunnels for tool instances via the Cloudflare API
+
+### Modified Capabilities
+
+- `instance-proxy`: The current proxy-based approach will be replaced by Cloudflare tunnels. The requirement that "The API SHALL expose an endpoint that forwards HTTP requests" is replaced by "The system SHALL provide a public URL for each running instance."
+
+## Impact
+
+- Backend: New Cloudflare tunnel service, updated instance lifecycle (create tunnel on start, delete on stop), removed proxy code
+- Frontend: Update "Open" links to use public Cloudflare URLs
+- Infrastructure: New `cloudflared` Docker service, Cloudflare API token required
+- Environment: New env vars: `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_ZONE_ID`
+- Docker: Cloudflared container must be on the same network as tool instances