Deploy by project type
Dockerfile apps
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 context | The whole repository root. Paths in COPY are relative to it. |
| Ignored files | Everything listed in .dockerignore at the root |
| Stage that runs | The last stage of a multi-stage Dockerfile |
| Architecture | linux/amd64 |
| Time limit | 45 minutes per build |
| Build arguments | None 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(orENTRYPOINT) 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
.dockerignoresonode_modules,.gitand local.envfiles never reach the build. - No secrets in the image — no
COPY .env, noENV API_KEY=…. Secrets are environment variables, given at runtime. - Don't rely on
VOLUMEor 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)
# ---- 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)
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:
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
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
.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-periodgives 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:
wgetis in Alpine images,curloften isn't, and slim Python images have neither — usepython -cas 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.
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
ARGwith no dashboard variable of that name keeps its default from the Dockerfile — give everyARGa 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:
docker build --platform linux/amd64 -t my-app .
docker run --rm -p 3000:3000 -e PORT=3000 my-app
# then open http://localhost:3000On 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.