Self-Hosting

RondoFlow ships with a single docker-compose.yml that builds and runs the whole stack — database, backend, frontend, and documentation — in containers. This page covers what each service does, how to bring them up, how to create the first admin, and — importantly — which .env variables actually reach the running containers (it is a smaller set than you might expect).

If you only want to develop locally, see Installation instead. Running the stack needs only Docker Desktop. The one exception is bootstrapping the first admin, which currently runs the database seed — see Create the first admin for both a Docker-only command and a host-Node option.

Services

Compose defines five services. The migrate service runs once and exits; the other four are long-running.

Startup order is enforced through health checks and depends_on:

• postgres must be healthy (pg_isready) before server and migrate start.
• migrate runs npx prisma migrate deploy --schema=prisma/schema.prisma against the database and exits with restart: "no".
• server is healthy once GET /api/health responds.
• docs is healthy once GET /docs responds.
• ui waits for both server and docs to report healthy before it starts.

Bring it up

git clone https://github.com/rondoflow/rondoflow.git
cd rondoflow
cp .env.example .env   # edit before continuing — see "Required configuration"
docker compose up --build

npm run docker:all          # docker compose up --build (foreground)
npm run docker:all:detach   # same, detached (-d)
npm run docker:down         # stop everything

The first build compiles three images and may take several minutes. The migrate container applies the schema, but it does not seed — and RondoFlow is invite-only, so there is no self-registration. Create the first admin account before signing in (see Create the first admin below), then open http://localhost:3000 and log in with those credentials.

# Watch logs for a single service
docker compose logs -f server
 
# Re-run migrations after pulling new code
docker compose up migrate

What env actually reaches the containers

This is the single most surprising thing about the Docker setup, so it gets its own section. The compose server service only forwards the variables listed in its environment: block — not your whole .env. Anything else you set in .env is read by the host npm scripts but never makes it into the container.

The server service forwards exactly these:

server:
  environment:
    PORT: "3001"
    DATABASE_URL: postgresql://rondoflow:rondoflow_dev@postgres:5432/rondoflow
    BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET:-change-me-generate-a-real-secret}
    BETTER_AUTH_URL: http://localhost:3001
    UI_ORIGIN: http://localhost:3000
    ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
    CLAUDE_CODE_OAUTH_TOKEN: ${CLAUDE_CODE_OAUTH_TOKEN:-}
    GITHUB_CLIENT_ID: ${GITHUB_CLIENT_ID:-}
    GITHUB_CLIENT_SECRET: ${GITHUB_CLIENT_SECRET:-}
    GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID:-}
    GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET:-}
    EXTERNAL_FOLDERS_CONTAINER_ROOT: ${EXTERNAL_FOLDERS_CONTAINER_ROOT:-/external}

Everything else documented in .env.example is not forwarded by default. To make these take effect in Docker, add them to the server service’s environment: block (or, for the credential ones, set them at runtime in Settings → Credentials — see Settings-managed credentials):

Settings-managed credentials

RondoFlow can store credentials in the database, encrypted, and load them into the process environment at boot. The encrypted Setting rows override the .env/container values when the server starts (loadSettingsIntoEnv() runs before the auth layer is built and before any Assistant is spawned).

This means a value you set in Settings → Credentials beats the same variable in the container env. The credentials managed this way are: the Claude keys, the OpenAI / Perplexity provider keys, the GitHub / Google OAuth pairs, and the SMTP set. Secret fields (SMTP_PASS, OAuth secrets, the provider keys) are encrypted at rest with AES-256-GCM.

The docs proxy in production

The documentation site runs as its own container with Next.js basePath set to /docs. Rather than exposing port 3002 to users, the UI reverse-proxies it so the docs live at <host>/docs on the same origin as the app.

The proxy origin is the DOCS_ORIGIN variable — but for the production (standalone) build it is a build arg, baked at build time, not a runtime env var. External (absolute-URL) rewrites like the /docs proxy are frozen into routes-manifest.json by next build, so a runtime env var cannot change them. In compose, DOCS_ORIGIN is therefore set under ui.build.args:

ui:
  build:
    args:
      DOCS_ORIGIN: http://docs:3002   # baked into the build — this is the one that matters
  environment:
    DOCS_ORIGIN: http://docs:3002     # kept for `npm run dev` parity; IGNORED by the prod image

The UI’s next.config.mjs reads DOCS_ORIGIN (defaulting to http://localhost:3002 for local dev) and rewrites both the page route and all sub-paths to it:

const DOCS_ORIGIN = process.env.DOCS_ORIGIN ?? 'http://localhost:3002';
 
async rewrites() {
  return [
    { source: '/docs', destination: `${DOCS_ORIGIN}/docs` },
    { source: '/docs/:path*', destination: `${DOCS_ORIGIN}/docs/:path*` },
  ];
}

In dev mode (npm run dev) Next reads the value at runtime, which is why the environment.DOCS_ORIGIN entry is kept for parity. In the Docker prod image only the build arg has any effect — the runtime environment.DOCS_ORIGIN is inert. To point the proxy somewhere else for a production build, change the build arg and rebuild the ui image.

Because the docs app already sets basePath: '/docs', the destination keeps the /docs prefix — it is not stripped. This single pair of rules proxies HTML, the _next/* assets, and the Pagefind search index in one hop.

External folders

Assistants work against real directories on disk. In Docker, every registered folder must live under one in-container root, and you bind-mount your host project directories into it.

Two variables control this on the server service:

The default mount in docker-compose.yml maps the host path to /external:

server:
  volumes:
    - ${EXTERNAL_FOLDERS_HOST_PATH:-./external}:/external:rw

Drop project folders under EXTERNAL_FOLDERS_HOST_PATH and they appear in the UI automatically. To expose specific host paths, add more bind mounts — they must land under /external:

server:
  volumes:
    - /home/me/projects/foo:/external/foo:rw   # read-write
    - /mnt/data/bar:/external/bar:ro           # read-only

Use the :ro suffix for directories an Assistant should read but never modify. Only change EXTERNAL_FOLDERS_CONTAINER_ROOT if you also change the mount target in compose. See External Folders for how folders surface in the workspace.

Required configuration

Edit .env at the repo root before bringing the stack up. Remember from What env actually reaches the containers that compose only interpolates the variables listed in each service’s environment: block.

# Generate a strong secret
openssl rand -hex 32
 
# Obtain a setup token to use your Claude subscription instead of an API key
claude setup-token

Create the first admin

A fresh stack has no accounts: RondoFlow is invite-only and the migrate container only runs prisma migrate deploy — it does not seed. The first admin is created by the seed, which reads RONDOFLOW_ADMIN_EMAIL and RONDOFLOW_ADMIN_PASSWORD (optional RONDOFLOW_ADMIN_NAME, default Administrator). The seed is idempotent: it skips if either var is blank, and re-running ensures the account exists and carries the admin role.

Important: those admin variables are not part of any compose service, so the migrate/server containers never see them. Run the seed yourself, with the variables present, against a reachable Postgres. Two ways:

# Bring up the database (and the rest of the stack) first
docker compose up -d postgres migrate
 
# Seed the first admin inside a throwaway server container
docker compose run --rm \
  -e RONDOFLOW_ADMIN_EMAIL=admin@example.com \
  -e RONDOFLOW_ADMIN_PASSWORD='a-strong-password' \
  -e DATABASE_URL=postgresql://rondoflow:rondoflow_dev@postgres:5432/rondoflow \
  server npx prisma db seed --schema=prisma/schema.prisma

# Postgres up and reachable on localhost:5432
docker compose up -d postgres migrate
 
# RONDOFLOW_ADMIN_EMAIL / RONDOFLOW_ADMIN_PASSWORD set in .env
npm run db:seed

Sign in with that account, then invite everyone else from the Users panel. See Users & Roles for the role model and invite flow.

Running as root

The server image runs as root (there is no USER directive in the Dockerfile). The Claude Code CLI refuses --dangerously-skip-permissions (what bypassPermissions mode forwards) when running as root, unless the environment is marked sandboxed. To keep bypassPermissions working in the container, the spawner auto-sets IS_SANDBOX=1 when it detects it is running as root with a bypass request — you do not normally need to set it yourself.

Production checklist

Image notes

Both the UI and docs images use Next.js standalone output, enabled by DOCKER_BUILD=1 at build time. The runtime images copy three things out of the build stage:

• .next/standalone — the self-contained server bundle
• .next/static — hashed static assets
• public — copied explicitly, since standalone output does not include it

The UI runs node packages/ui/server.js; the docs site runs node packages/docs/server.js on port 3002. The server image’s working directory is /app/packages/server, and its CMD runs the Fastify entry with npx tsx src/index.ts (so the schema path inside the container is relative, e.g. prisma/schema.prisma).

Related