Deploy by project type

Dockerfile apps

Bring your own Dockerfile when you need full control: a particular base image, system libraries (ffmpeg, Chromium, GDAL…), a language automatic builds don't cover, or a build you want to be exactly reproducible. The platform builds it and runs the result.

How it works#

If a file named exactly Dockerfile sits at the root of your repository (and there is no deployable Compose file), the repository is built from it:

Build contextThe whole repository root. Paths in COPY are relative to it.
Ignored filesEverything listed in .dockerignore at the root
Stage that runsThe last stage of a multi-stage Dockerfile
Architecturelinux/amd64
Time limit45 minutes per build
Build argumentsNone are passed — see below

Deploy it with New → Web service, and make the container listen on port 3000. (A Dockerfile that serves static files on port 80 — nginx, Caddy — is deployed as a Static site instead.)

EXPOSE doesn't choose the port

EXPOSE is documentation only. Traffic always goes to port 3000 for a Web service, so the process inside must actually listen on 3000, on 0.0.0.0. Set ENV PORT=3000 in the Dockerfile so frameworks that read PORT pick it up.

Rules for a good Dockerfile here#

  • Use a multi-stage build: compile in one stage, copy only the output into a small runtime stage.
  • End with CMD (or ENTRYPOINT) that starts a production server in the foreground.
  • Add a HEALTHCHECK — deploys wait for it to pass (see below).
  • Run as a non-root user where the base image allows it.
  • Add a .dockerignore so node_modules, .git and local .env files never reach the build.
  • No secrets in the image — no COPY .env, no ENV API_KEY=…. Secrets are environment variables, given at runtime.
  • Don't rely on VOLUME or writing to disk — the filesystem resets on every deploy.
  • No dev servers as CMD (npm run dev, nodemon, uvicorn --reload).

Examples#

Node.js (Express, NestJS, Fastify)

Dockerfile
# ---- dependencies + build ----
FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build              # remove if you have no build step

# ---- runtime ----
FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production PORT=3000
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
HEALTHCHECK --interval=15s --timeout=5s --start-period=20s --retries=3 \
  CMD wget -qO- http://127.0.0.1:3000/health || exit 1
CMD ["node", "dist/server.js"]

Python (FastAPI)

Dockerfile
FROM python:3.12-slim
WORKDIR /app
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PORT=3000

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

RUN useradd --create-home app
USER app
EXPOSE 3000
# slim images have no curl or wget — use Python itself for the check.
HEALTHCHECK --interval=15s --timeout=5s --start-period=30s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:3000/health', timeout=4)"
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "3000", "--proxy-headers", "--forwarded-allow-ips", "*"]

Next.js (standalone output)

Set output: 'standalone' in next.config.js for a much smaller image:

Dockerfile
FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
ENV NODE_ENV=production PORT=3000 HOSTNAME=0.0.0.0
COPY --from=build /app/.next/standalone ./
COPY --from=build /app/.next/static ./.next/static
COPY --from=build /app/public ./public
USER node
EXPOSE 3000
CMD ["node", "server.js"]

Go

Dockerfile
FROM golang:1.23-alpine AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/app .

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/app /app
ENV PORT=3000
EXPOSE 3000
ENTRYPOINT ["/app"]

.dockerignore

.dockerignore
.git
node_modules
dist
.next
__pycache__
*.pyc
.venv
.env
.env.*
!.env.production
docker-compose*.yml
Dockerfile*

Health checks: use HEALTHCHECK#

Every deploy waits for your container to be running — and if the image defines a HEALTHCHECK, for it to report healthy. A release that never becomes healthy fails the deploy with the reason in the log, instead of silently replacing a working version with a broken one.

  • --start-period gives slow starters (migrations, model loading) time before failures count.
  • The check runs inside your container, so the tool it uses must be in the image: wget is in Alpine images, curl often isn't, and slim Python images have neither — use python -c as in the example.
  • This is more reliable than the dashboard's Health-check path field, which you should leave empty (why).

Build arguments and build-time values#

Each ARG your Dockerfile declares receives the dashboard variable of the same name, if there is one. Variables your Dockerfile doesn't declare are not passed to the build.

Dockerfile
FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
# Set VITE_API_URL in the dashboard; it arrives here.
ARG VITE_API_URL
ENV VITE_API_URL=$VITE_API_URL
RUN npm run build
  • The value is copied into the build, so changing it needs a new build: press Settings → Redeploy.
  • An ARG with no dashboard variable of that name keeps its default from the Dockerfile — give every ARG a sensible default.
  • Anything only needed at runtime (database URLs, API keys) should simply be read from the environment when the app starts, not declared as an ARG. That is almost everything.
  • Never declare a secret as an ARG. Build arguments are recorded in the image's history, where anyone with the image can read them.

Private packages#

The build cannot use your personal npm, pip or GitHub credentials, and there is no build secret mechanism yet. Private dependencies need to be vendored into the repository or published somewhere the build can read without credentials.

Test it locally first#

If this works on your machine, it will build on the platform:

bash
docker build --platform linux/amd64 -t my-app .
docker run --rm -p 3000:3000 -e PORT=3000 my-app
# then open http://localhost:3000

On Apple Silicon the --platform flag matters: the servers are linux/amd64, and images built for arm64 won't run on them. The platform always builds for the right architecture itself.