Frontend Build and Deployment#

RAGFlow's frontend is a React 18 / TypeScript application (web/CLAUDE.md) built with Vite as the bundler (web/package.json). The compiled SPA is served by nginx running inside the Docker production container.

Tech Stack#

Key constraint: Node.js ≥ 18.20.4 (enforced via engine-strict=true in web/.npmrc). The .npmrc also pins the registry to https://registry.npmmirror.com/ 1.

Docker Multi-Stage Build#

The Dockerfile uses three stages:

1. base (lines 1–183) — Ubuntu 24.04 with system deps, nginx, and Node.js 20.x installed via the NodeSource repo 2.
2. builder (lines 187–243) — Installs npm dependencies, then compiles the frontend:
   • package.json/package-lock.json are copied first so source changes don't bust the npm install cache layer 3.
   • Builds via VITE_BUILD_SOURCEMAP=false VITE_MINIFY=esbuild npm run build with NODE_OPTIONS="--max-old-space-size=8192" 4.
3. production (lines 246–287) — Inherits base (no build tools), then copies only the compiled web/dist from builder 5.

For China CI, pass --build-arg NEED_MIRROR=1 to switch npm (and APT/PyPI) to Aliyun mirrors 6.

Local Development Workflow#

All commands run from the web/ directory 7 8:

npm install # install dependencies
npm run dev # Vite dev server with HMR
npm run build # production build → web/dist/
npm run lint # oxlint
npm run test # Jest with coverage

The Vite dev server proxies API calls to a running RAGFlow backend. Changes to source files are reflected immediately via HMR — no rebuild required. To see changes in a Docker deployment, you must npm run build and then rebuild/restart the container 9.

Common pitfall: Editing files under web/src/ and then accessing the running Docker container will show the old build. Always rebuild after source changes intended for production.

Nginx Configuration and SPA Routing#

At runtime, entrypoint.sh selects a nginx config variant based on the API_PROXY_SCHEME environment variable and copies it to /etc/nginx/conf.d/ragflow.conf before starting nginx 10.

All three variants share these traits 11:

• Serve static assets from /ragflow/web/dist (nginx root)
• SPA routing: try_files $uri $uri/ /index.html falls back to index.html for client-side routing 12
• Gzip compression enabled for JS, CSS, HTML, images 13
• Long-lived caching: expires 10y for /static/(css|js|media)/ paths 14
• Proxy API traffic (/v1, /api) to the backend with shared settings from proxy.conf (3600s timeouts, buffering disabled for streaming)

The top-level nginx.conf sets client_max_body_size 1024M to allow large file uploads and includes /etc/nginx/conf.d/ragflow.conf.

Key Files#