Working with Docker

This guide explains how to use Docker to locally develop, test, and serve your AWS Lambda boilerplate project.

Overview

Docker allows you to containerize the Lambda boilerplate for consistent development across machines, and for serving the documentation/landing page locally. The boilerplate includes:

  • Dockerfile — Multi-stage build for testing and artifact generation
  • docker-compose.yaml — Development environment orchestration
  • docker/docs.Dockerfile — Documentation and landing page server
  • docker/docker-compose.docs.yaml — Docs site composition

Prerequisites

  1. Install Docker Desktop:

  2. Verify installation:

    docker --version
docker compose --version

Development Container

Build the Development Image

The main Dockerfile creates a multi-stage build that:

  1. Installs dependencies
  2. Compiles TypeScript
  3. Runs tests
  4. Generates documentation
docker compose build

Run Tests in Container

Execute the full test suite in an isolated container:

docker compose up

This will:

  • Install all dependencies (npm ci)
  • Build the project (npm run build)
  • Run tests (npm run test)
  • Generate TypeDoc (npm run build:docs)

Output: All test results and coverage reports are generated in lib/, dist/docs/, and dist/coverage/

Interactive Development

Run a shell in the container to develop interactively:

docker run -it --rm -v $(pwd):/app bayudwiyansatria/aws-lambda-boilerplate:latest /bin/bash

Inside the container:

npm run build
npm run test:run
npm run lint:run

Volume Mounts

Keep your local source code in sync with the container:

docker run -it --rm \
  -v $(pwd)/src:/app/src \
  -v $(pwd)/test:/app/test \
  bayudwiyansatria/aws-lambda-boilerplate:latest \
  npm run test:run

Documentation & Landing Page Server

Build the Docs Container

The docker/docs.Dockerfile builds a complete documentation site with:

  • Landing page (nginx)
  • TypeDoc API reference
  • Test coverage HTML report
  • HonKit developer book
  • Dark theme with responsive design
docker compose -f docker/docker-compose.docs.yaml build

Run the Docs Site Locally

Serve the documentation site at http://localhost:8080:

docker compose -f docker/docker-compose.docs.yaml up

Access:

  • Landing page: http://localhost:8080/ (home page with navigation cards)
  • Documentation: http://localhost:8080/docs/ (TypeDoc API reference)
  • Coverage Report: http://localhost:8080/coverage/ (Jest test coverage)
  • Developer Book: http://localhost:8080/book/ (HonKit guides)

Configuration

The docs container uses docker/nginx/default.conf for routing:

server {
  listen 80;
  server_name _;
  root /usr/share/nginx/html;
  index index.html;

  absolute_redirect off;
  location / {
    try_files $uri $uri.html $uri/ /index.html;
  }
}

This allows:

  • /guide/deployments/quick-start → /guide/deployments/quick-start.html
  • /guide/deployments → /guide/deployments/ (directory index)
  • Unknown routes → fall back to /index.html

Customize Landing Page

Edit docker/nginx/index.html:

<div class="logo">B</div>  <!-- Logo character -->
<h1>AWS Lambda Boilerplate</h1>
<p>A modern starter template...</p>

Then rebuild:

docker compose -f docker/docker-compose.docs.yaml build

Docker Image Details

Main Image (Dockerfile)

Base: node:26-bookworm-slim

Stages:

  1. base — Node.js runtime
  2. build — Installs deps, compiles TypeScript, runs tests, generates docs

Output artifacts:

  • lib/ — Rollup CommonJS/ESM/UMD bundles
  • lib/index.d.ts — Generated TypeScript definitions
  • dist/docs/ — TypeDoc API documentation
  • dist/coverage/ — Jest coverage HTML report

Docs Image (docker/docs.Dockerfile)

Base: nginx:stable

Stages:

  1. build — Node.js multi-stage build (same as main)
  2. release — Nginx serving compiled docs

Output artifacts:

  • Serves all files from dist/ on port 80
  • Includes docker/nginx/default.conf for routing

Docker Commands Reference

Build

# Build main image
docker compose build

# Build docs image
docker compose -f docker/docker-compose.docs.yaml build

# Build specific service
docker compose build app

Run

# Run full pipeline in main container
docker compose up

# Run docs site
docker compose -f docker/docker-compose.docs.yaml up -d

# Run specific service
docker compose run app npm run test:run

# Interactive shell
docker run -it --rm -v $(pwd):/app bayudwiyansatria/aws-lambda-boilerplate:latest /bin/bash

Clean Up

# Stop running containers
docker compose down

# Remove images
docker compose down --rmi all

# Remove volumes
docker compose down -v

# Clean all Docker resources (⚠️ danger zone)
docker system prune -a

Best Practices

1. Use .dockerignore

Exclude unnecessary files from Docker build context:

node_modules
npm-debug.log
.git
.env
dist
lib
.DS_Store

2. Cache Layers Efficiently

Order Dockerfile instructions from least to most frequently changing:

  1. Copy package.json & package-lock.json (change infrequently)
  2. Run npm ci
  3. Copy source code (change frequently)

This way, dependency layer is cached and reused.

3. Use Docker Compose for Local Development

Much simpler than managing containers manually:

docker compose up --build

4. Keep Container Images Small

Use slim base images:

FROM node:26-bookworm-slim  # ~200 MB slim image
# Instead of:
FROM node:26                 # ~600 MB full image

5. Handle Secrets Safely

Never commit .env files with secrets. Use environment variable files securely:

# Create .env.local (not tracked in git)
echo "API_KEY=secret123" > .env.local

# Pass to container
docker compose --env-file .env.local up

Troubleshooting

"Docker daemon not running"

Start Docker Desktop or the Docker daemon:

  • Mac/Windows: Open Docker Desktop app
  • Linux: systemctl start docker

"Cannot connect to Docker daemon"

Ensure Docker is running and you have permissions:

sudo usermod -aG docker $USER
# Log out and back in for changes to take effect

Build fails with "npm ci" error

Clear npm cache and retry:

docker compose build --no-cache

Port 8080 already in use

Run docs on a different port:

docker run -p 8081:80 bayudwiyansatria/aws-lambda-boilerplate:docs

Then visit http://localhost:8081

Large image size

Use multi-stage build to exclude build tools from final image:

FROM node:26-bookworm-slim AS build
# ... build steps

FROM nginx:stable AS release
COPY --from=build /app/dist .
# Final image only contains nginx + dist files

CI/CD Integration

GitHub Actions Example

name: Build and Test

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: docker/setup-buildx-action@v2
      - run: docker compose build
      - run: docker compose run app npm run test
      - run: docker compose run app npm run lint:run

results matching ""

    No results matching ""