Docker Containerization Support for Evolution SDK

[mwihoti]

This PR introduces a complete, production-grade Docker containerization setup for the Evolution SDK. The goal is to eliminate the "works on my machine" problem by giving contributors and end-users a reproducible, isolated environment that mirrors production — without requiring manual installation of Node.js, pnpm, or TypeScript.

Description

Setting up the Evolution SDK locally requires specific versions of Node.js, pnpm, and TypeScript, which can be inconsistent across developer machines and CI environments.

This PR solves that by containerizing the entire SDK workflow — from development with hot reload, to testing and documentation serving, to a minimal production runtime image.

It also lays the groundwork for future CI/CD pipelines and significantly improves onboarding for new contributors.

---

📁 Files Added

File	Purpose
Dockerfile	Primary multi-stage build: base → development → builder → production
Dockerfile.multi	Extended multi-stage file with test stage, HEALTHCHECK, and build-arg support
Dockerfile.docs	Dedicated image for the Next.js documentation site
docker-compose.yml	Orchestrates dev, docs, test runner, and Cardano devnet node
docker-build.sh	Convenience shell script with colored output for Docker workflows
docker-help.sh	Interactive helper script explaining available Docker commands
DOCKER.md	Full documentation: quick start, building, running, CI/CD examples, troubleshooting

---

🛠️ Implementation Details

Multi-Stage Dockerfile (Dockerfile / [Dockerfile.multi]
primary uses a carefully layered multi-stage build:
node:20-alpine (base) ├── corepack + pnpm via corepack (no npm install -g) Minimal Alpine system packages: git, bash, curl, jq
Lockfile-first COPY for optimal layer caching ├── pnpm install --frozen-lockfile (cached via --mount=type=cache) └── pnpm turbo build --filter=@evolution-sdk/* ├── development → pnpm turbo dev (hot reload) ├── test → pnpm turbo test (CI runner) └── builder → pnpm prune --prod └── production → ~200MB minimal runtime image

Key design decisions:

• BuildKit cache mounts (--mount=type=cache,id=pnpm) dramatically speed up repeated builds by reusing the pnpm store across builds
• Lockfile-first layer — COPY pnpm-lock.yaml ... ./ before source code means dependency layers are only invalidated when dependencies change
• pnpm prune --prod in the builder stage removes all devDependencies before copying into the slim production image
• node:20-alpine as the base keeps images lean — production image is ~200MB vs ~800MB for development

Docker Compose (docker-compose.yml)

Four services managed together:

Service	Description	Port
evolution-dev	Full dev environment with live volume mounts	3000
evolution-docs	Next.js docs site (Dockerfile.docs)	3000
evolution-test	Runs pnpm turbo test, exits on completion	—
cardano-devnet	Local Cardano preview network node	3001
Volume mounts for evolution-dev preserve node_modules inside the container while reflecting live source edits from the host (./packages:/app/packages).

Script

Build Script (docker-build.sh)
A colored, idiomatic bash script wrapping all Docker commands:

./docker-build.sh dev        # Build development image
./docker-build.sh prod       # Build production image (tagged with package.json version)
./docker-build.sh test       # Run test suite inside container
./docker-build.sh start-dev  # Start dev environment via docker-compose
./docker-build.sh cleanup    # docker-compose down -v + docker system prune
./docker-build.sh all        # Build dev + prod in one command
# Image Sizes
Image	Approximate Size
evolution-sdk:dev	~800MB (all dev dependencies)
evolution-sdk:prod	~200MB (production only)
evolution-sdk-docs:latest	~250MB (Next.js + deps)
✅ Testing Done
 Built evolution-sdk:dev image locally with ./docker-build.sh dev
 Built evolution-sdk:prod image — verified it only contains production dependencies
 Ran pnpm turbo build inside the container successfully
 Ran pnpm turbo test via ./docker-build.sh test — all tests passed
 Started docker-compose up -d evolution-dev — dev server came up on port 3000
 Verified volume mounts reflect live code changes without rebuilding
 Verified Node.js version and pnpm version resolve correctly inside container
 Confirmed .dockerignore excludes node_modules, .git, build artifacts