Docker Build & Test

This guide covers building and testing the Docker image locally.

Building the Image

Basic Build

docker build -t chromium-pdf-service:latest .

Build with Version Tag

# With specific version
docker build -t chromium-pdf-service:1.0.0 .

# With multiple tags
docker build -t chromium-pdf-service:latest -t chromium-pdf-service:1.0.0 .

Build with No Cache

docker build --no-cache -t chromium-pdf-service:latest .

Build with Build Arguments

docker build \
  --build-arg NODE_ENV=production \
  -t chromium-pdf-service:latest .

Running the Container

Basic Run

docker run -d -p 3000:3000 chromium-pdf-service:latest

Run with Environment Variables

docker run -d \
  -p 3000:3000 \
  -e NODE_ENV=production \
  -e LOG_LEVEL=info \
  -e RATE_LIMIT_MAX=100 \
  -e API_KEYS=my-secret-key \
  chromium-pdf-service:latest

Run with Volume Mounts

docker run -d \
  -p 3000:3000 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/pdf-files:/app/pdf-files \
  -v $(pwd)/logs:/app/logs \
  chromium-pdf-service:latest

Run with All Options

docker run -d \
  --name pdf-service \
  -p 3000:3000 \
  -e NODE_ENV=production \
  -e LOG_LEVEL=info \
  -e RATE_LIMIT_MAX=50 \
  -e API_KEYS=key1,key2 \
  -e BLOCK_PRIVATE_IPS=true \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/pdf-files:/app/pdf-files \
  -v $(pwd)/logs:/app/logs \
  --restart unless-stopped \
  chromium-pdf-service:latest

Testing the Container

1. Check Container Status

# List running containers
docker ps

# Check container logs
docker logs pdf-service

# Follow logs in real-time
docker logs -f pdf-service

2. Test Health Endpoints

# Health check
curl http://localhost:3000/health

# Readiness probe
curl http://localhost:3000/health/ready

# Liveness probe
curl http://localhost:3000/health/live

Expected response:

{"status":"healthy","timestamp":"2025-01-01T00:00:00.000Z"}

3. Test PDF Generation

# Generate PDF from HTML
curl -X POST http://localhost:3000/api/pdf/html \
  -H "Content-Type: application/json" \
  -H "X-API-Key: my-secret-key" \
  -d '{
    "requestedKey": "test-001",
    "html": "<h1>Hello World</h1><p>Test PDF</p>"
  }'

# Check job status
curl http://localhost:3000/api/pdf/status/test-001 \
  -H "X-API-Key: my-secret-key"

# Download PDF (when completed)
curl -O http://localhost:3000/api/pdf/download/test-001 \
  -H "X-API-Key: my-secret-key"

4. Test URL to PDF

curl -X POST http://localhost:3000/api/pdf/url \
  -H "Content-Type: application/json" \
  -H "X-API-Key: my-secret-key" \
  -d '{
    "requestedKey": "example-page",
    "url": "https://example.com"
  }'

Docker Compose

Development

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Production

# Build and start
docker-compose -f docker-compose.yml up -d --build

# Scale (if needed)
docker-compose up -d --scale pdf-service=2

Troubleshooting

Container Won't Start

# Check logs for errors
docker logs pdf-service

# Check if port is in use
lsof -i :3000

# Run interactively for debugging
docker run -it --rm chromium-pdf-service:latest /bin/bash

PDF Generation Fails

# Check Chromium is working
docker exec -it pdf-service npx playwright install --dry-run

# Check available memory
docker stats pdf-service

# Increase memory limit
docker run -d --memory=2g chromium-pdf-service:latest

Permission Issues

# Check volume permissions
ls -la ./pdf-files

# Fix permissions
chmod 777 ./pdf-files ./data ./logs

Browser Crashes

Add these flags if browser crashes:

docker run -d \
  --shm-size=2gb \
  -p 3000:3000 \
  chromium-pdf-service:latest

Performance Tips

1. Use Multi-Stage Build

The Dockerfile already uses multi-stage builds to minimize image size.

2. Set Resource Limits

docker run -d \
  --memory=2g \
  --cpus=2 \
  -p 3000:3000 \
  chromium-pdf-service:latest

3. Use Health Checks

docker run -d \
  --health-cmd="curl -f http://localhost:3000/health || exit 1" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-retries=3 \
  -p 3000:3000 \
  chromium-pdf-service:latest

4. Optimize for Production

# docker-compose.prod.yml
services:
  pdf-service:
    image: chromium-pdf-service:latest
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

CI/CD Integration

Automated Publishing

This project uses GitHub Actions to automatically build and publish Docker images to GitHub Container Registry (ghcr.io).

Workflow:

1. Push a version tag (e.g., git tag v1.0.0 && git push --tags)
2. Tests workflow runs automatically
3. On test success, Docker image is built for linux/amd64 and linux/arm64
4. Image is pushed to ghcr.io/chromium-pdf/chromium-pdf-service

Versioning:

Git Tag	Docker Tags
v1.2.3	1.2.3, 1.2, 1, latest
v0.0.2-alpha	0.0.2-alpha

Manual Trigger

You can also manually trigger a build from GitHub Actions:

1. Go to Actions → "🐳 Publish Docker Image"
2. Click "Run workflow"
3. Optionally specify a custom tag

Local CI Testing

# Test locally before pushing
- name: Build Docker image
  run: docker build -t chromium-pdf-service:${{ github.sha }} .

- name: Test Docker image
  run: |
    docker run -d -p 3000:3000 --name test chromium-pdf-service:${{ github.sha }}
    sleep 5
    curl -f http://localhost:3000/health
    docker stop test

Creating a Release

# Create and push a version tag
git tag v1.0.0
git push origin v1.0.0

# The workflow will automatically:
# 1. Run all tests
# 2. Build multi-platform image
# 3. Push to ghcr.io/chromium-pdf/chromium-pdf-service:1.0.0