Deploying Apps/Dockerfile

Dockerfile Requirements

Hatch is Dockerfile-first. If your app can build into a container and serve traffic on a port, Hatch can deploy it.

Container nativeNo framework lock-inPort matters

Runtime contract

Hatch does not need to understand your framework. It only needs a container that starts reliably and responds over HTTP.

Requirement	Why it matters
Dockerfile	Hatch builds the image from the Dockerfile path configured on the project.
0.0.0.0 binding	The load balancer cannot reach a process bound only to localhost.
Known port	The project port is used for target group traffic and health checks.
Health path	Hatch waits for a healthy target before marking the deployment live.

Common runtime shapes

Static frontend

nginx

Build assets, serve them through NGINX, expose port 80

Node app

node

Install dependencies, set HOST and PORT, start the server

Go API

Compile a binary, copy it into a small image, expose the API port

Python API

python

Run ASGI/WSGI on 0.0.0.0 with a configured port

Static site example

Dockerfile

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

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80

Hatch detects EXPOSE 80 and uses it as the service port. The default health check path / should work for most static sites.

Node server example

Dockerfile

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
ENV HOST=0.0.0.0
ENV PORT=3000
EXPOSE 3000
CMD ["npm", "start"]

If your app ignores HOST, configure it in framework code. Listening on localhost is the most common cause of healthy local builds that fail in production.