Install with Docker / Docker Compose

Run the dFlow control plane from the official Compose stack: prerequisites, env files, and first boot.

Written By Zoro

Last updated 3 days ago

This guide supersedes the legacy “one-click template” install article.

You run the stack from the dFlow source tree (or your vendor image tags) with Docker Compose.

Prerequisites

  • A Linux host (VM or bare metal) with Docker and Docker Compose v2
  • Enough RAM and disk for MongoDB, Redis, Traefik, and the dFlow app container
  • A wildcard DNS (or planned hostname strategy) if you expose the UI and proxy on your own domain; see Domains and SSL

1. Get the repository layout

From your checkout of dFlow, open:

  • docker-compose.yml: service topology (Traefik, MongoDB, Redis, app, monitoring helpers)
  • DOCKER.md: environment variables, ports, and operational notes
  • SELF_HOSTING.md: longer bootstrap narrative for VM-focused installs

2. Configure environment variables

Create a .env (or follow DOCKER.md for the exact file names your team uses) with at least:

  • Database credentials for MongoDB
  • Redis URI-compatible settings if you override defaults
  • Payload / app secrets (PAYLOAD_SECRET, etc.)
  • Tailscale keys if you use the documented tailnet integration
  • Proxy and public URL variables (NEXT_PUBLIC_WEBSITE_URL, wildcard domain, and related proxy settings)

Never commit real secrets; use your secret manager in production.

3. Prepare Traefik files

Compose expects traefik.yaml, acme.json, and a dynamic/ directory beside docker-compose.yml. Create acme.json as an empty file and chmod 600 acme.json before the first Traefik start. If your checkout does not ship a ready traefik.yaml, add one from your internal runbook or adapt the sample from your infrastructure team.

4. Start the stack

docker compose up -d

Wait for MongoDB, Redis, and Traefik to become healthy before loading the UI.

5. Verify

  1. Open the dashboard URL you configured.
  2. Complete first-time Organisation setup if prompted.
  3. Add or attach a Worker Node when you are ready to run Services: Attach compute to an environment under Environments in the sidebar.

What runs in Compose (high level)

TraefikTerminates TLS and routes HTTP(S) to the app and related services
MongoDBPrimary application database
RedisCaching and job-related usage
payload-appdFlow Next.js / Payload application
Beszel / agentsHost monitoring (as wired in your docker-compose.yml)

Exact service names and images can change between releases; trust your checked-in docker-compose.yml over this table when they differ.

Next steps

Related