Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/betterspacx/app/llms.txt

Use this file to discover all available pages before exploring further.

Betterflow is a standard Next.js application and can be self-hosted on any platform that supports Node.js. The two officially supported deployment targets are Vercel (the recommended path for most teams) and Docker for containerized or on-premise environments. This page covers both options and lists every environment variable you will need to configure.

​
Deploying to Vercel

Vercel is the recommended deployment target for Betterflow. Because the project is built on Next.js, Vercel handles all framework-specific optimisations — including serverless API routes, edge caching, and automatic preview deployments — with no additional configuration.
1

Connect your repository

Go to vercel.com, create a new project, and import your fork or copy of the Betterflow repository. Vercel will detect the Next.js framework automatically.
2

Configure build settings

Vercel auto-detects the correct values for a Next.js project, but verify the following in the project settings before your first deploy:
SettingValue
Framework PresetNext.js
Build Commandpnpm run build
Output Directory.next
Install Commandpnpm install
Vercel’s default install command is npm install. You must override it to pnpm install because the project’s preinstall hook (only-allow pnpm) will fail the build if any other package manager is used.
3

Set environment variables

In your Vercel project dashboard, navigate to Settings → Environment Variables and add the variables listed in the Environment Variables table below. At minimum, set NEXT_PUBLIC_SITE_URL to your production domain.To enable hosted background images, add all of the Cloudflare R2 variables as well. Other variables are optional and can be added later.
4

Deploy

Trigger your first deployment by clicking Deploy in the Vercel dashboard, or push a commit to your main branch. Vercel will run pnpm run build (which includes drizzle-kit generate before the Next.js build) and publish the resulting .next output.Subsequent pushes to main will redeploy automatically.

​
Deploying with Docker

Betterflow supports containerised deployment for teams that need on-premise hosting, custom infrastructure, or full control over the runtime environment.
The repository does not currently include a Dockerfile. Before running the commands below, you must add your own Dockerfile to the repository root. The example commands assume a standard multi-stage Node.js image that builds with pnpm run build and starts with pnpm start.
Build the Docker image from the repository root: 
docker build -t betterflow .
Run the container, forwarding port 3000 and passing your environment variables: 
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_SITE_URL=https://your-domain.com \
  -e NEXT_PUBLIC_R2_PUBLIC_URL=https://your-r2-bucket-url \
  -e R2_ACCESS_KEY_ID=your_access_key \
  -e R2_SECRET_ACCESS_KEY=your_secret_key \
  -e R2_BUCKET_NAME=your_bucket_name \
  -e CLOUDFLARE_ACCOUNT_ID=your_account_id \
  -e R2_API_TOKEN=your_api_token \
  betterflow
Alternatively, use an .env file with Docker’s --env-file flag: 
docker run -p 3000:3000 --env-file .env betterflow
For production Docker deployments, build the production bundle first with pnpm run build and start the server with pnpm start (which runs next start) rather than using the dev server.

​
Environment Variables

The table below covers every variable from .env.example. Copy .env.example to .env (or enter these directly into your Vercel dashboard) and fill in the values for your deployment.
VariableRequiredDescription
NEXT_PUBLIC_SITE_URLRequiredThe canonical public URL of your deployment, e.g. https://your-domain.com. Used in SEO metadata.
NEXT_PUBLIC_FIREBASE_API_KEYOptionalFirebase project API key.
NEXT_PUBLIC_FIREBASE_AUTH_DOMAINOptionalFirebase Auth domain.
NEXT_PUBLIC_FIREBASE_PROJECT_IDOptionalFirebase project ID.
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKETOptionalFirebase Storage bucket.
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_IDOptionalFirebase messaging sender ID.
NEXT_PUBLIC_FIREBASE_APP_IDOptionalFirebase app ID.
CLOUDFLARE_ACCOUNT_IDRequired for backgroundsYour Cloudflare account ID.
R2_ACCOUNT_IDRequired for backgroundsYour R2-specific account ID.
R2_ACCESS_KEY_IDRequired for backgroundsAccess key for the R2 API.
R2_SECRET_ACCESS_KEYRequired for backgroundsSecret key for the R2 API.
R2_BUCKET_NAMERequired for backgroundsName of the R2 bucket that stores background images and uploaded assets.
R2_API_TOKENRequired for backgroundsR2 API token used by server-side routes.
NEXT_PUBLIC_R2_PUBLIC_URLRequired for backgroundsPublic base URL of your R2 bucket, e.g. https://pub-xxxx.r2.dev.
NEXT_PUBLIC_R2_CUSTOM_DOMAINOptionalCustom domain placed in front of R2 for asset serving.
NEXT_PUBLIC_CDN_URLOptionalCDN base URL for serving R2 assets through a caching layer.
NEXT_PUBLIC_POSTHOG_KEYOptionalPostHog analytics API key for usage tracking.
NEXT_PUBLIC_POSTHOG_HOSTOptionalPostHog ingest host. Defaults to https://us.i.posthog.com.
GOOGLE_SITE_VERIFICATIONOptionalGoogle Search Console meta-tag verification token.
CLEANUP_SECRETOptionalBearer token that protects the /api/cleanup-cache route.
The R2 variables are only needed if you want to serve hosted background images from a Cloudflare R2 bucket. All core editor functionality — including device frames, 3D transforms, animations, and video export — works without any R2 configuration.

​
What’s Next

Environment Variables

Full reference for every configuration option.

Quickstart

Run Betterflow locally for development.

Build docs developers (and LLMs) love

Get started for freeTalk to us