Appearance
Self-hosting overview
FlowRunner is a single Next.js application backed by one MongoDB database. This section is the operations runbook for running it on your own infrastructure — what you need, how a deploy is shaped, and how to keep it healthy.
What you need
You do not need a cluster of services. FlowRunner is deliberately built to run on the smallest possible footprint.
| Requirement | Notes |
|---|---|
| Node 20 or newer | The runtime for the Next.js server. |
| Yarn | The package manager. Never run npm install — it rewrites the lockfile and breaks the build. |
| One MongoDB database | Atlas or self-hosted. This is the only datastore. |
| A host for the Next.js server | Vercel, a container, or a plain VM. |
WARNING
Always use Yarn for installs and scripts. Running npm install (or npm remove) breaks the lockfile and can produce a deploy that builds locally but fails in CI or production.
Architecture in one sentence
FlowRunner stores everything in MongoDB — your projects, form submissions, encrypted secrets, uploaded files (via GridFS), run history, schedules, and custom domains — so a single database connection string is all the app needs to run.
That means there is no separate object store, no Redis, no queue to operate. Rate limiting and file storage both live in Mongo. Fewer moving parts means a simpler backup story and a shorter list of things that can break.
The deploy shape
A deploy is four moves:
- Configure the environment variables — two are required, the rest each toggle an optional feature. See Environment variables.
- Build and start the server with Yarn (or push to Vercel, which runs the build for you).
- Verify the app is live and reaching the database by hitting
GET /api/health. See Health & monitoring. - Wire scheduled triggers if you use them — a single external timer that pings the tick endpoint once a minute. See Scheduled triggers wiring.
The database indexes create themselves on first access, so there is no migration step for a fresh install. The one-time exception is an existing single-owner install being upgraded to multi-tenancy — covered in First deploy.
TIP
src/lib/env.ts is the single source of truth for what a deploy needs. It validates the environment at boot: missing required variables fail fast with a clear error; missing optional ones log a warning and quietly disable that feature.