Dockerise a Waku app

Build a Docker Image

Bundle your Waku app into a Docker image for portability and deployment in container-based environments.

Prerequisites

Make sure Docker is installed on your machine. This guide assumes an npm-based Waku app. If your project uses pnpm or another package manager, use the matching lockfile and install commands in the Dockerfile.

Dockerfile

Create a Dockerfile in your project root:

FROM node:22-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

FROM node:22-alpine AS runner

WORKDIR /app
ENV NODE_ENV=production

COPY package*.json ./
RUN npm ci --omit=dev

COPY --from=builder /app/dist ./dist

EXPOSE 8080

CMD ["npm", "run", "start"]

This Dockerfile uses Docker's multi-stage build pattern:

• the builder stage installs all dependencies and runs npm run build
• the runner stage installs production dependencies and copies only the built dist output
• the container starts the app with npm run start

A health check command can be optionally included at the end of the Dockerfile. An example would be: HEALTHCHECK --interval=30s CMD wget -qO- http://localhost:8080 || exit 1

.dockerignore file

Use an ignore file to avoid copying unnecessary/undesirable files into the image. For example:

/node_modules
.git
dist
.vscode

This way node_modules files will not be copied in the above Dockerfile setup.

Compose File

To streamline local container startup, create a compose file:

services:
  waku-app:
    build:
      context: .
    image: waku-app
    environment:
      NODE_ENV: production
    ports:
      - '8080:8080'

Specify the name of the service, and within it add the following:

• build context ( cwd ) where the build process should take place
• image name so that the correct image is used to create the container
• environment variables
• port forwarding so the app is accessible on the host machine (e.g. in your browser)

Build the container

Finally, build and start the container:

docker compose up --build

The app should be available at http://localhost:8080.