Builds without a Dockerfile

A plain Node, Bun, Python or Go project deploys with keel deploy and nothing else: when the project has no Dockerfile, Keel detects the runtime, renders a multi-stage Dockerfile and builds it. The same detection runs on the CLI local build path (keel deploy), on the platform git build path (LocalDockerImageBuilder on the single host, the CodeBuild project on Fargate) and in keel init --dockerfile, so a project builds the same way everywhere. The code lives in packages/buildpacks (@keel/buildpacks).

What happens on keel deploy

1. build.dockerfile in keel.yaml names a file: it must exist and it is used as is.
2. Otherwise a Dockerfile at the root of the build context is used as is.
3. Otherwise the runtime is detected and a Dockerfile is rendered into a temporary directory (keel-build-*/Dockerfile.keel), with a Dockerfile.keel.dockerignore next to it when the project has no .dockerignore. Nothing is written into the project; docker build --file points at the temporary file and the directory is removed after the push. The detection summary and the Dockerfile are printed on stderr.
4. keel deploy --print-dockerfile prints the Dockerfile that step 2 or 3 would use and exits without deploying (--json adds the detection). keel init --dockerfile writes it into the project as Dockerfile (and .dockerignore when missing), after which keel deploy uses that file and generation stops.

On the platform path the source binding's Dockerfile path is now nullable; null (the default, an empty field in the dashboard form) means the same three steps run on the checkout, and keel.yaml in the repository supplies the build: overrides and the ingress port. The build log starts with the detection summary and the Dockerfile, and ImageBuild.detectedRuntime (for example node 22, python 3.12 (fastapi), go 1.23) is shown on the build in the dashboard, in keel deploy --json and on GET /v1/builds/{id}.

Detection rules

The project is one runtime. Two markers of different runtimes (say package.json and go.mod) are refused with ambiguous_runtime until build.runtime picks one. Every refusal names the file or setting that fixes it.

Node and Bun

Marker: package.json.

Python

Marker: pyproject.toml, requirements.txt (a Pipfile alone is refused with the export command to run).

Go

Marker: go.mod.

Static sites

index.html without any of the markers above is not a runtime: keel deploy refuses and points at keel sites.

Overrides in keel.yaml

build:
  runtime: node            # node | bun | python | go
  packageManager: pnpm     # npm | pnpm | yarn | bun | pip | uv | poetry
  buildCommand: null       # a shell string, or null to skip the build step
  startCommand: node dist/server.js
  nodeVersion: 22          # a Node major, 18 or newer
  pythonVersion: "3.11"    # quote it so YAML keeps 3.10
  goVersion: "1.22"
ingress:
  port: 3000               # the image sets ENV PORT and EXPOSE to this, default 8080

build.dockerfile must be a relative path inside the project made of letters, digits, dot, dash, underscore and slash, with no .. segment (the same rule as the API's dockerfilePath); build.context and build.platform keep their meaning (The CLI). buildCommand and startCommand are one line each without control characters. The schema is buildOverridesSchema in @keel/buildpacks, embedded in the CLI's keel.yaml parser; the platform reads the same section from the repository's keel.yaml through readBuildSettings.

Generated Dockerfile properties

• Multi-stage: dependencies and the build in one stage, a clean runtime stage that copies only the result. NODE_ENV=production, PYTHONUNBUFFERED=1, PORT=<port> and EXPOSE <port> are set in the runtime stage.
• Never root: node, bun, a dedicated app user for Python, nonroot on distroless for Go. Files are copied with --chown.
• Base images are pinned by major (Node, Bun, Go) or major.minor (Python) tag. Digest pinning is a follow-up: the platform would have to refresh digests on a schedule, and a stale digest is worse than a floating patch tag.
• No secrets are baked: nothing reads .env (it is in the synthesized .dockerignore with .git, node_modules, .venv, caches and, when a build step regenerates them, dist, build and .next), and the platform injects secrets at run time.
• Lifecycle scripts run: npm ci, pnpm install, yarn install and bun install execute the postinstall scripts of the lockfile's packages, as they would on a laptop. --ignore-scripts breaks packages that compile or download at install time (esbuild, sharp, prisma), so Keel does not add it. The install runs inside the build container of the customer's own build, not on shared infrastructure, and the resulting image runs as a non root user under the platform egress policy. Audit your lockfile if this matters to you.
• CMD is exec form whenever the command is plain; commands with $PORT or quotes run through sh -c "exec ..." so the server is still PID 1 and receives SIGTERM.
• Every string that comes from the project (buildCommand, startCommand, a Procfile line, a cmd/<name> directory) is rendered as a JSON exec-form RUN ["sh","-c",...] or CMD [...], never spliced into a shell-form instruction, so no value from the repository can add Dockerfile instructions. File names that would need quoting in a command are refused or skipped instead of quoted.

The platform build path

• LocalDockerImageBuilder (single host, IMAGE_BUILDER=local) calls prepareBuildContext on the checkout, writes Dockerfile.keel and the .dockerignore into it for the build and removes them afterwards.
• The CodeBuild buildspec (infra/terraform/modules/build/buildspec.yml) downloads the bundled CLI keel-buildpacks.mjs from the build tools bucket (keel-build-tools-<environment>, uploaded by Terraform from packages/buildpacks/dist/keel-buildpacks.mjs, so run pnpm --filter @keel/buildpacks build before terraform plan) and runs keel-buildpacks prepare /tmp/source [--dockerfile <path>]. It prints the detection and the Dockerfile to the build log, writes the files into the checkout and answers {"dockerfile": ..., "runtime": ...}; the buildspec exports DETECTED_RUNTIME next to IMAGE_DIGEST.
• keel-buildpacks print <dir> prints the Dockerfile without writing; exit code 3 means detection refused, with the reason on stderr.

Examples

Express with npm, scripts.start: node server.js, engines.node: ">=20":

FROM node:24-slim AS base
WORKDIR /app

FROM base AS build
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY . .

FROM base
ENV NODE_ENV=production \
    PORT=8080
COPY --from=build --chown=node:node /app ./
USER node
EXPOSE 8080
CMD ["npm","start"]

FastAPI with uv (pyproject.toml, uv.lock, main.py):

FROM python:3.12-slim AS build
ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
    PIP_NO_CACHE_DIR=1 \
    VIRTUAL_ENV=/opt/venv \
    PATH=/opt/venv/bin:$PATH
WORKDIR /app
RUN python -m venv /opt/venv
RUN pip install --no-cache-dir "uv<1"
ENV UV_PROJECT_ENVIRONMENT=/opt/venv \
    UV_COMPILE_BYTECODE=1 \
    UV_LINK_MODE=copy
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-install-project
COPY . .
RUN uv sync --frozen --no-dev

FROM python:3.12-slim
ENV VIRTUAL_ENV=/opt/venv \
    PATH=/opt/venv/bin:$PATH \
    PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PORT=8080
WORKDIR /app
RUN groupadd --system app \
    && useradd --system --gid app --create-home --home-dir /home/app app
COPY --from=build --chown=app:app /opt/venv /opt/venv
COPY --from=build --chown=app:app /app /app
USER app
EXPOSE 8080
CMD ["sh","-c","exec uvicorn main:app --host 0.0.0.0 --port $PORT"]

Go with main.go at the module root:

FROM golang:1.23 AS build
WORKDIR /src
COPY go.* ./
RUN go mod download
COPY . .
ENV CGO_ENABLED=0 \
    GOOS=linux
RUN go build -trimpath -ldflags="-s -w" -o /out/server .

FROM gcr.io/distroless/static-debian12:nonroot
ENV PORT=8080
WORKDIR /app
COPY --from=build /out/server /app/server
USER nonroot:nonroot
EXPOSE 8080
CMD ["/app/server"]

Tests

pnpm --filter @keel/buildpacks test runs the fixture projects under packages/buildpacks/test/fixtures (every runtime, the overrides, and each refusal). pnpm --filter @keel/buildpacks test:docker builds the Node fixture with the generated Dockerfile from a temporary directory, runs it with PORT=9090, and checks the answer, the non root uid and that the ignored .env is not in the image. packages/infrastructure/src/builds/local-build.test.ts does the same through LocalDockerImageBuilder and checks the log and detectedRuntime.