Sub-Path (BASE_PATH) Support Summary

Date: 2025-09-24

This document summarizes the changes that add support for hosting Flowise under a sub-path (e.g., http://localhost:3000/path) instead of only at the domain root (e.g., http://localhost:3000).

Overview

Flowise can now be deployed under a base path using the following environment variables:

• Server: BASE_PATH
• UI (Vite): VITE_BASE_PATH

These variables allow you to mount both the API and the UI at a sub-path. For example, when BASE_PATH=/path, the application is served at http://<host>:<port>/path and the API lives under http://<host>:<port>/path/api/v1.

Environment Variables

• BASE_PATH (server)

  • Purpose: Mounts server routes, static assets, and the UI under the specified sub-path.
  • Example: BASE_PATH=/path
  • Notes: No trailing slash. If empty or unset, Flowise behaves as before (root path).

• VITE_BASE_PATH (UI)

  • Purpose: Configures the React Router basename and Vite base path for correct asset and route resolution during development/build.
  • Example: VITE_BASE_PATH=/path
  • Notes: Required only for local UI development/builds. For the packaged UI served by the server, the server’s BASE_PATH is sufficient at runtime.

Key Changes

• Server

  • Respect BASE_PATH when mounting API routes, static UI assets, and queue dashboard:
    • API router mounted at "${BASE_PATH}/api/v1"
    • IP helper endpoint at "${BASE_PATH}/api/v1/ip"
    • BullMQ dashboard (when enabled) at "${BASE_PATH}/admin/queues"
    • Static UI served at BASE_PATH (or / when not set)
  • Whitelist checks account for BASE_PATH-prefixed URLs.
  • BASE_PATH accepted as a CLI flag (npx flowise start --BASE_PATH=/path).

• UI

  • React Router configured with basename from VITE_BASE_PATH.
  • Vite base set from VITE_BASE_PATH and dev server proxy updated to forward "${VITE_BASE_PATH}/api" to the server.
  • Frontend constants build API/UI URLs using VITE_BASE_PATH when present.

• Docker

  • .env.example updated to document BASE_PATH.
  • docker-compose.yml and queue variants pass BASE_PATH to the container.
  • Healthchecks updated to call http://localhost:${PORT}${BASE_PATH}/api/v1/ping.
  • Docker README clarifies how to access the app when BASE_PATH is set (e.g., http://localhost:3000/path).

Backward Compatibility

• If BASE_PATH/VITE_BASE_PATH are not set, Flowise operates unchanged at the root (/).