Integration

Docker

Deploy NextReport Engine as a Docker container with Chromium support for PDF rendering.

Overview

The NextReport Engine ships as a lightweight Docker image. Running it in a container gives you a self-contained, reproducible environment with all dependencies — including headless Chromium for PDF rendering.

Quick start

Build the image

docker build -t nextreport-engine .

Run the container

docker run -p 3000:3000 nextreport-engine

The engine is now available at http://localhost:3000.

Verify

curl http://localhost:3000/api/templates

Docker Compose

For development and multi-service deployments, use Docker Compose:

# docker-compose.yml
version: '3.8'

services:
  nextreport:
    build: .
    ports:
      - '3000:3000'
    environment:
      - NODE_ENV=production
      - PORT=3000
      - LOG_LEVEL=info
      - PDF_ENABLED=true
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 512M

Start the stack:

docker compose up -d

Environment variables

Configure the engine at runtime with environment variables:

VariableDefaultDescription
PORT3000HTTP server port
NODE_ENVdevelopmentdevelopment or production
LOG_LEVELinfodebug, info, warn, error
PDF_ENABLEDtrueEnable PDF rendering (requires Chromium)
CHROMIUM_PATH(auto)Custom Chromium binary path
MAX_PAGES100Maximum pages per render request
TIMEOUT_MS30000Render timeout in milliseconds

Example

docker run -p 3000:3000 \
  -e NODE_ENV=production \
  -e LOG_LEVEL=warn \
  -e MAX_PAGES=50 \
  -e TIMEOUT_MS=15000 \
  nextreport-engine

Chromium for PDF

PDF rendering requires headless Chromium. The official Docker image includes it automatically. If you are building a custom image, install the required dependencies:

Debian / Ubuntu base

FROM node:22-slim

# Install Chromium dependencies
RUN apt-get update && apt-get install -y \
    chromium \
    fonts-liberation \
    libatk-bridge2.0-0 \
    libdrm2 \
    libgbm1 \
    libgtk-3-0 \
    libnss3 \
    libx11-xcb1 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    --no-install-recommends \
  && rm -rf /var/lib/apt/lists/*

# Set Chromium path for Puppeteer
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
ENV PUPPETEER_SKIP_DOWNLOAD=true

WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install --prod
COPY . .

EXPOSE 3000
CMD ["node", "dist/server.js"]

Alpine base

FROM node:22-alpine

RUN apk add --no-cache \
    chromium \
    nss \
    freetype \
    harfbuzz \
    ca-certificates \
    ttf-freefont

ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
ENV PUPPETEER_SKIP_DOWNLOAD=true

WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install --prod
COPY . .

EXPOSE 3000
CMD ["node", "dist/server.js"]

Disabling PDF

If you only need HTML output, disable PDF rendering to skip Chromium entirely:

docker run -p 3000:3000 -e PDF_ENABLED=false nextreport-engine

This produces a smaller, faster container. Requests for PDF format will return a 400 error with a message indicating PDF support is disabled.

Health check

The engine exposes a health endpoint:

curl http://localhost:3000/health

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "pdf": true
}

Add a health check to your Docker Compose configuration:

services:
  nextreport:
    # ...
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:3000/health']
      interval: 30s
      timeout: 10s
      retries: 3

Production tips

  • Memory limits: Set deploy.resources.limits.memory to at least 256MB (512MB if PDF is enabled)
  • Concurrency: Each PDF render consumes a Chromium tab. For high-throughput workloads, scale horizontally
  • Font support: Mount custom fonts into /usr/share/fonts/ for brand-specific typography
  • Logging: Set LOG_LEVEL=warn in production to reduce noise

Next steps