Dockerfiles

floo builds from the Dockerfile in your repo. Every service you deploy needs one. The full set of requirements is the container contract. This page covers writing the file itself.

Checklist

Build succeeds from a clean checkout
Process binds to $PORT on 0.0.0.0
All runtime dependencies in the final image
CMD or ENTRYPOINT starts the service
One Dockerfile per service directory
A .dockerignore beside it, so COPY . . cannot overwrite an installed dependency tree with your local one. See Build context.

Monorepos

A service builds with its own path as the context, so it cannot read files above that directory. If your services share workspace packages, set dockerfile to build from the repository root instead. See Monorepos. floo init does not write a Dockerfile for a workspace repository, because the generated templates copy only the root manifest and cannot install one.

Registry caching

Use standard Docker Hub images in your Dockerfile. floo routes pulls through a regional cache with no configuration, so layers are served from the cache instead of being pulled from Docker Hub on every build.

What `floo init` writes

floo init detects the runtime and writes one of these templates. They are the reference shape for a floo Dockerfile: multi-stage, EXPOSE $PORT, and a start command that reads $PORT. Base images: node:22-slim, python:3.13-slim (or the major.minor from requires-python in pyproject.toml), and golang:1.23 (or the version in go.mod) with a gcr.io/distroless/static final stage.

Node.js (Next.js)

FROM node:22-slim AS deps
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci

FROM node:22-slim AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:22-slim
WORKDIR /app
COPY --from=build /app/.next ./.next
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/package.json ./
EXPOSE $PORT
CMD ["npm", "start"]

next start reads PORT from the environment. A pnpm or yarn project gets the matching lockfile copy, install, build, and start commands.

Python (FastAPI)

FROM python:3.13-slim AS deps
WORKDIR /app
COPY pyproject.toml requirements*.txt* ./
RUN pip install --no-cache-dir -r requirements.txt 2>/dev/null || pip install --no-cache-dir .

FROM python:3.13-slim
WORKDIR /app
COPY --from=deps /usr/local/lib/python3.13/site-packages /usr/local/lib/python3.13/site-packages
COPY --from=deps /usr/local/bin /usr/local/bin
COPY . .
EXPOSE $PORT
CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port $PORT"]

The shell form is what lets $PORT expand. Flask and Django templates use the same stages with gunicorn <module> --bind 0.0.0.0:$PORT.

Go

FROM golang:1.23 AS build
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o server .

FROM gcr.io/distroless/static
COPY --from=build /app/server /server
EXPOSE $PORT
CMD ["/server"]

The binary must read PORT itself and listen on 0.0.0.0.

Container contract

Every requirement an image must meet, and the diagnostic each one raises.

Build context

Which files reach the build, and how to keep large or sensitive files out.

Get started

Build with your stack

Deploy

Managed services

Environments

Operate

Access

For agents

Dockerfiles

Checklist

Monorepos

Registry caching

What `floo init` writes

Node.js (Next.js)

Python (FastAPI)

Go

Container contract

Build context

​Checklist

​Monorepos

​Registry caching

​What floo init writes

​Node.js (Next.js)

​Python (FastAPI)

​Go

Container contract

Build context

Checklist

Monorepos

Registry caching

What `floo init` writes

Node.js (Next.js)

Python (FastAPI)

Go