Deploy Flowise v3.1.2: LLM Workflow Builder Setup Guide

Here’s the mistake that breaks most Flowise deployments: people copy the old npm install -g flowise command from a 2023 tutorial, set FLOWISE_USERNAME + FLOWISE_PASSWORD, and ship it. Then they wonder why their instance behaves oddly, or worse – gets compromised. As of v3.0.1, that auth method is deprecated. Flowise now uses Passport.js with JWT cookies, and if you skip generating proper secrets, you’re running on weak defaults.

So let’s reverse-engineer the deploy. The goal: a Flowise v3.1.2 instance (current stable as of March 2026) on Docker, with real auth, patched against CVE-2025-59528, and surviving the breaking change v3.0.11 quietly introduced.

Why deploy Flowise as your LLM workflow builder

Four modules under the hood: a Node server backend, a React UI, integration components, and Swagger API docs. That split matters when something breaks – errors almost always point to one specific module, which narrows debugging fast. Source code is Apache License 2.0, so commercial self-hosting is fine without a separate agreement.

The honest pitch: it’s faster than writing LangChain code from scratch, slower than a managed platform like Flowise Cloud, and a much bigger attack surface than either. Self-hosting makes sense if you need on-prem data, custom node code, or you’ve hit Cloud’s pricing wall. If none of those apply – Cloud is probably the better call.

System requirements

RAM is the gotcha. Build from source with under ~4 GB free and you’ll hit exit code 134 – JavaScript heap out of memory. Fix: export NODE_OPTIONS="--max-old-space-size=4096" before running pnpm build. On a 1 vCPU / 1-2 GB VPS, skip the source build entirely and use the prebuilt Docker image instead.

That said – most tutorials hand you the install commands and move on. The config step is where they abandon you, and it’s also where most production incidents start. Worth slowing down there.

Install Flowise v3.1.2 with Docker (recommended)

Skip the global npm install for production. Docker gives you a reproducible environment and keeps the Node version isolated from whatever else is on your host. The official image is flowiseai/flowise on Docker Hub – but pin the tag rather than using :latest, unless you enjoy surprise breaking changes on Monday morning.

# Clone the repo for docker-compose files
git clone https://github.com/FlowiseAI/Flowise.git
cd Flowise/docker

# Copy the example env file
cp .env.example .env

# Edit .env (see config section below) - DO THIS BEFORE STARTING
nano .env

# Start it
docker compose up -d

Open http://localhost:3000. On first load with auth enabled, you’ll see a setup screen prompting you to create an admin account – that’s the new Passport.js flow, not a bug.

Alternative: npm (dev/testing only)

npm install -g flowise works on Node 18.15+ or 20+. Start with npx flowise start, open http://localhost:3000. Fine for kicking the tires. Not fine for anything public-facing.

First-time configuration that actually matters

Four separate secrets. That’s not overkill – the Passport.js auth system (introduced in v3.0.1 per the official auth docs) issues a short-lived access token and a long-lived refresh token, and each secret handles a different part of that pipeline. Flowise detects weak or missing values and treats them as unset, which means it falls back to auto-generated secrets – opaque to debug and not reproducible across restarts.

Minimum .env for a secure-ish instance:

PORT=3000
DATABASE_PATH=/root/.flowise
SECRETKEY_PATH=/root/.flowise
LOG_PATH=/root/.flowise/logs

# Generate each with: openssl rand -hex 32
JWT_AUTH_TOKEN_SECRET=<32-byte-hex>
JWT_REFRESH_TOKEN_SECRET=<32-byte-hex>
EXPRESS_SESSION_SECRET=<32-byte-hex>
TOKEN_HASH_SECRET=<32-byte-hex>

# Token lifetimes - adjust to your security policy (60 min access / 90-day refresh are the documented defaults)
JWT_TOKEN_EXPIRY_IN_MINUTES=360
JWT_REFRESH_TOKEN_EXPIRY_IN_MINUTES=43200

# Keep this ON unless you know what you're doing (see HTTP_SECURITY_CHECK section below)
HTTP_SECURITY_CHECK=true

Pro tip: Generate all four secrets in one shot: for v in JWT_AUTH_TOKEN_SECRET JWT_REFRESH_TOKEN_SECRET EXPRESS_SESSION_SECRET TOKEN_HASH_SECRET; do echo "$v=$(openssl rand -hex 32)"; done – pipe straight into your .env.

Verify the install works

Three checks, in order:

1. Container is up:docker compose ps – status should be running, not restarting.
2. Server responds:curl -I http://localhost:3000 – expect HTTP 200 or 302 (redirect to login).
3. Auth setup screen loads: visit the URL in a browser – you should see the admin account creation form.

Container on a restarting loop? Check docker compose logs flowise. Nine times out of ten it’s a missing env var or a port conflict on 3000.

Common errors and the fixes that actually work

504. OOM. Container stops immediately. Pick your problem.

1. Container starts then immediately stops

Reported on QNAP Container Station and similar NAS setups: installs fine, starts, stops. Cause is almost always a missing writable volume for DATABASE_PATH. Fix: mount a host volume to /root/.flowise and confirm the container user has write access.

2. Outbound LLM calls hang with 504 errors

Deploying on-prem behind a corporate proxy? The application loads – but turns out the container can’t make outbound requests to OpenAI, HuggingFace, or anything else, even though curl from the same host works fine. The container needs its own proxy env vars set, not just the host:

environment:
 - HTTP_PROXY=http://your.proxy:port
 - HTTPS_PROXY=http://your.proxy:port
 - http_proxy=http://your.proxy:port
 - https_proxy=http://your.proxy:port

3. Local Ollama / internal vector DB suddenly unreachable

This one is silent and confusing. Starting in v3.0.11, Flowise enables HTTP security validation by default – a deny list blocking requests to localhost, 127.0.0.1, and other internal addresses to mitigate SSRF attacks. If your flow called an Ollama instance at http://localhost:11434, it stopped working after that upgrade with no obvious error message.

Options: set HTTP_SECURITY_CHECK=false only if you fully control what runs on the instance, or route Ollama through a DNS name and reverse proxy instead of a raw localhost address.

4. “no configuration file provided”

Commonly reported (e.g., GitHub discussions) – running docker-compose up -d from the wrong directory. The compose file lives in Flowise/docker/, not the repo root. cd there first.

Upgrade path and uninstall

v3.0.6. That’s the line.

Anything before it is exposed to CVE-2025-59528 (CVSS 10.0) – an RCE in the CustomMCP node that lets an attacker execute arbitrary JavaScript on your Flowise server with only an API token. Patch notes are in the GitHub Advisory GHSA-3gcm-f6qx-ff7p.

Upgrade via Docker:

cd Flowise/docker
docker compose pull
docker compose down
docker compose up -d

Crossing from a pre-v3.0.0 install? The auth schema changed significantly. Per the migration notes, plan to set up your admin account fresh rather than assuming old user records carry over – the docs recommend verifying this against your specific version jump.

Full uninstall:

docker compose down -v # -v removes volumes too
rm -rf ~/.flowise # purges DB, secrets, logs
docker image rm flowiseai/flowise

For npm installs: npm uninstall -g flowise and delete ~/.flowise.

FAQ

Can I run Flowise without Docker?

Yes. npm install -g flowise on Node 18.15+ or 20+. Local dev only.

Do I still need FLOWISE_USERNAME and FLOWISE_PASSWORD?

No – those belong to the old auth flow, deprecated since v3.0.1. The new system prompts you to create an admin account on first launch and stores credentials in the database. The old env vars are ignored on v3.0.1+, so if you’ve been relying on them for access control, your instance may be less protected than you think. Check the auth docs to confirm your setup.

What’s the file upload limit for RAG documents?

FLOWISE_FILE_SIZE_LIMIT defaults to 50 MB (as of v3.1.2). Bump it in your .env for large PDFs – but Node buffers the whole file in memory during upload, so on a 1 GB VPS you’ll hit OOM before you hit the limit.

Next step: Once your instance is up and verified, lock down the Prometheus metrics endpoint at /api/v1/metrics with an API key before exposing port 3000 to the internet. The monitoring docs walk through the bearer-token config.