The Docpipe web UI is a visual tool for building, running, and monitoring document processing pipelines.
It is served by the FastAPI backend and is accessible at /ui on whichever host you have deployed Docpipe to.
http://localhost:3000/uihttp://localhost:8080/uihttps://<your-route-host>/uiThe application header contains four primary navigation items:
| Item | URL pattern | Purpose |
|---|---|---|
| Home | /ui/home |
Overview dashboard — recent projects, flows, and runs |
| Projects | /ui/projects |
Manage projects and their flows |
| Canvas | /ui/canvas/:flowId |
Visual pipeline editor (opened from a flow) |
| Runs | (accessible from a project) | Job run history and status |
The Home page provides an at-a-glance overview with three summary cards:
Click any item in a card to navigate directly to it.
The Projects page lists all projects. A project is a logical container for one or more pipelines (flows).
Creating a project
Click Create project in the top-right corner of the page. Enter a name and an optional description. The project appears in the list immediately after creation.
Opening a project
Click on any project card to open its detail view, which shows the flows that belong to it.
Editing or deleting a project
Use the overflow menu (⋮) on the project card to rename, edit the description, or delete the project.
Inside a project you see the list of flows. A flow is a directed pipeline of operators: it defines which operators run, in what order, and with what configuration.
Creating a flow
Click Create flow. Enter a name and optional description. The flow is saved to the project.
Opening a flow in the canvas
Click on any flow card to open the visual canvas editor for that flow.
Editing or deleting a flow
Use the overflow menu (⋮) on the flow card.
The Canvas is the visual pipeline editor. It opens when you click a flow.
The left panel lists all available operators grouped by category (Ingest, Extract, Functional, Quality, VectorDB, Storage). Drag an operator from the palette onto the canvas to add it to your pipeline.
Click Run in the canvas toolbar. The pipeline is submitted to the backend as a job. A notification appears when the run starts. Click View run (or navigate to the Runs page) to follow progress.
Click the Flow run history button in the toolbar to see all past runs for this flow with their status and duration.
Click About flow in the toolbar to view and edit the flow name and description without leaving the canvas.
The Runs page (accessible from within a project) lists all job runs for that project. Each row shows:
PENDING, RUNNING, COMPLETED, FAILEDClick any row to open the Run details page, which shows per-operator status, document counts, and error messages.
| Term | Meaning |
|---|---|
| Project | A logical container for one or more flows |
| Flow | A directed acyclic graph (DAG) of operators that defines a pipeline |
| Operator | A single processing step (ingest, extract, chunk, embed, store, etc.) |
| Node | An operator instance placed on the canvas |
| Link | A connection between two nodes that defines data flow |
| Job run | A single execution of a flow |
1. Create a project
2. Create a flow inside the project
3. Open the flow in the canvas
4. Drag an Ingest operator onto the canvas and configure the file path or source
5. Add downstream operators (Extract, Chunker, Embeddings, VectorDB)
6. Connect them in order
7. Click Run
8. Monitor progress on the Runs page
Symptoms can have different causes depending on how you started the UI. Find your deployment mode below.
npm run dev)Blank page or nothing loads at http://localhost:3000/ui
npm run dev should show output from both BFF and VITE prefixes.frontend/.env exists. If not, run cp .env.example .env from the frontend/ directory and restart.BACKEND_API_URL in frontend/.env points to where FastAPI is actually running (default: http://localhost:8080).Canvas shows no operators in the palette
The browser cannot reach the backend API through the BFF. Open the browser developer console (F12) and check for errors on the Network tab.
net::ERR_CONNECTION_REFUSED on /api/* — the BFF is not running. Check the BFF prefix output in the terminal; if it exited, re-run npm run dev.404 from the BFF — the FastAPI backend is not running. Start it: uvicorn docpipe.api.main:app --host 0.0.0.0 --port 8080.BACKEND_API_URL in frontend/.env.BFF exits immediately with BACKEND_API_URL is not set
frontend/.env is missing or empty. Run cp .env.example .env from the frontend/ directory.
uvicorn docpipe.api.main:app)UI not accessible at http://localhost:8080/ui
The frontend assets were not bundled into the wheel. Rebuild them manually and restart:
cd frontend && npm install && npm run build
python scripts/build_frontend.py
uvicorn docpipe.api.main:app --host 0.0.0.0 --port 8080
Canvas shows no operators — backend logs show “BFF not started: node not found”
node is not in PATH. Install Node.js (any version ≥ 18) and ensure it is on the system PATH, then restart the server.
Canvas shows no operators — backend logs show “BFF not started: bff/server.cjs not found”
The BFF bundle was not included in the wheel. Run python scripts/build_frontend.py from the project root to rebuild the assets and bundle, then restart.
A service is not healthy
docker compose -f docker/all-in-one-deployment/docker-compose.yml ps
docker compose -f docker/all-in-one-deployment/docker-compose.yml logs bff
docker compose -f docker/all-in-one-deployment/docker-compose.yml logs docpipe
Canvas shows no operators after the stack is healthy
The docpipe container depends on bff being healthy before it starts. If the BFF container restarted after docpipe came up, FastAPI may have lost its BFF URL. Restart the docpipe container:
docker compose -f docker/all-in-one-deployment/docker-compose.yml restart docpipe
UI route returns 502 or connection refused
Check that the BFF pod is running and healthy, and that BFF_URL is set correctly on the backend deployment:
oc get pods -l app=docpipe-bff
oc logs deployment/docpipe-bff
oc get env deployment/docpipe-backend | grep BFF_URL
A run stays in PENDING forever
The backend started the job but an operator cannot reach an external service. Check the FastAPI logs for connection errors to Ollama, OpenSearch, or other configured services.
Page loads but all API calls return 401 Unauthorized
Authentication is not yet enforced in the UI. If you are seeing 401 responses, the backend JWT configuration may be misconfigured. Check JWT_SECRET_KEY in your .env file.