skills.rest
ZaxbyHub
ZaxbyHubOFFICIAL
Explore all skills by this author →
GitHub

subpath-deployment

Configures reverse-proxy subpath deployment for a FastAPI and Vite React application.

Updated Mar 30, 2026
Search Tags:#fastapi#docker#vite#reverse proxy#sse streaming#subpath deployment#cookie path
One-click install
npx skills add https://github.com/ZaxbyHub/ragappv3 --skill subpath-deployment-zaxbyhub
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: subpath-deployment
Source: https://github.com/ZaxbyHub/ragappv3/tree/main/.opencode/skills/subpath-deployment
Command: npx skills add https://github.com/ZaxbyHub/ragappv3 --skill subpath-deployment-zaxbyhub

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Deploying a web app under a URL prefix (e.g., /meridian) behind a reverse proxy breaks cookie paths, SPA routing, API base URLs, and streaming unless backend, frontend build, and proxy configs are coordinated. This Skill encodes the locked architectural decisions so agents do not reintroduce known bugs like runtime prefix detection or hardcoded /api fallbacks. ## Core Features & Use Cases - Three-variable contract: Documents how APP_ROOT_PATH, VITE_APP_BASENAME, and VITE_API_URL interact across backend runtime, Docker build args, and proxy config. - Locked decisions: Prefix-stripping proxy only, prefix-agnostic backend, build-time frontend prefix, no X-Forwarded-Prefix detection, and cookie Path matching the browser-visible URL. - Edge-case guidance: Covers the tsconfig composite-project boundary for vite.config.ts, the is_unstripped_prefix() 404 guard, dev proxy parity, streaming headers for NGINX, and fetch-based SSE auth instead of EventSource. - Use Case: When changing the deployment prefix from /knowledgevault to /meridian, follow the documented rebuild-and-reconfigure walkthrough without touching application code. ## Quick Start Load this skill before modifying anything related to APP_ROOT_PATH, VITE_APP_BASENAME, cookie paths, SPA catch-all routing, or frontend Docker build args, then follow its locked decisions.

Frequently Asked Questions about subpath-deployment

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I deploy a Vite React app under a subpath behind a reverse proxy?▼

Set VITE_APP_BASENAME as a Docker build arg so Vite bakes the prefix into base and BrowserRouter basename at build time. Configure the proxy to strip the prefix before forwarding, and set APP_ROOT_PATH on the backend for cookie paths and FastAPI root_path.

How do I change the URL prefix of an existing deployment?▼

Rebuild the frontend image with the new VITE_APP_BASENAME build arg, update APP_ROOT_PATH on the backend, and update the reverse proxy to strip the new prefix. No code changes are required; a root-built image cannot be fixed at runtime.

Why are auth cookies not sent on subpath API requests?▼

The browser matches cookie Path against the URL bar path, not the backend internal path. A cookie scoped to /api/auth/refresh will not be sent to /meridian/api/auth/refresh, so all set_cookie calls must use the prefixed path helpers.

Can I use EventSource for authenticated SSE endpoints?▼

No. EventSource cannot set custom headers, so Bearer-token auth always returns 401. Use fetch with an Authorization header, read the response body stream, parse SSE lines manually, and retry after refreshing the token on token_expired.

Why does NGINX break streaming responses from FastAPI?▼

NGINX's default proxy_buffering batches chunks and breaks streaming UX. Every StreamingResponse must include X-Accel-Buffering: no and Cache-Control: no-cache headers to disable buffering.

Why can't vite.config.ts import from the src directory?▼

vite.config.ts runs under tsconfig.node.json while src files belong to tsconfig.json in a composite project. Importing across them causes a composite build conflict, so shared logic like normalizeBasePath is duplicated with cross-reference comments.

Related Skills

Explore More Software Engineering Skills→
JansenAnalyticsJansenAnalytics
5

nginx-caddy

Configure Nginx or Caddy as a secure reverse proxy with SSL/TLS.

Community
Intermediate
mattothomasmattothomas

land-and-deploy

Merge a PR, wait for CI, deploy, and verify production health via canary checks.

Community
Advanced
tachfineamnaytachfineamnay

Security

Orchestrate authentication, authorization, and secrets management for web applications.

Community
Intermediate
golemcloudgolemcloud
1.5k

golem-configure-api-domain

Configures HTTP API domain deployments and OIDC security schemes in golem.yaml manifests.

Official
Intermediate