Processor Dockerfile

Processors run as Docker containers. The Dockerfile defines the container environment. The examples below show recommended patterns for Bun/TypeScript processors. Python and .NET have different patterns documented in their respective sections.

Minimal Dockerfile

FROM oven/bun:1.3.8

WORKDIR /app

# Required: Mark as CyanPrint processor
LABEL cyanprint.dev=true

# Install dependencies
COPY package.json .
COPY bun.lockb .
RUN bun install

# Copy processor code
COPY . .

# Run processor
CMD ["bun", "run", "index.ts"]

Required Elements

LABEL cyanprint.dev=true

This label identifies the container as a CyanPrint processor. Without it, the processor won't be recognized:

LABEL cyanprint.dev=true

WORKDIR

Set the working directory. The convention is /app:

WORKDIR /app

CMD

The command that runs the processor:

# Bun
CMD ["bun", "run", "index.ts"]

# Node.js
CMD ["node", "index.js"]

# Python
CMD ["python", "-u", "main.py"]

# .NET (use ENTRYPOINT instead)
ENTRYPOINT ["dotnet", "Processor.dll"]

Using Node.js

If you prefer Node.js over Bun:

FROM node:20-alpine

WORKDIR /app

LABEL cyanprint.dev=true

# Install dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy processor code
COPY . .

CMD ["node", "index.js"]

Using Python

Python processors use a different pattern:

FROM python:3.12.12

WORKDIR /app

LABEL cyanprint.dev=true

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy processor code
COPY . .

CMD ["python", "-u", "main.py"]

Using .NET

.NET processors use multi-stage builds and require explicit port configuration:

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app

FROM --platform=$BUILDPLATFORM mcr.microsoft.com/dotnet/sdk:8.0 AS build
ARG TARGETARCH
WORKDIR /src
COPY ["Processor.csproj", "./"]
RUN dotnet restore -a $TARGETARCH "Processor.csproj"
COPY . .
WORKDIR "/src/"
RUN dotnet build "Processor.csproj" -a $TARGETARCH -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "Processor.csproj" -a "$TARGETARCH" -c Release -o /app/publish /p:UseAppHost=false

FROM base AS final
LABEL cyanprint.dev=true
ENV ASPNETCORE_URLS=http://+:5551
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "Processor.dll"]

Multi-Stage Build

For smaller images with compiled code:

# Build stage
FROM oven/bun:1.3.8-alpine AS builder

WORKDIR /app

COPY package.json .
COPY bun.lockb .
RUN bun install

COPY . .
RUN bun build index.ts --outdir=dist --target=bun

# Runtime stage
FROM oven/bun:1.3.8-alpine

WORKDIR /app

LABEL cyanprint.dev=true

COPY --from=builder /app/dist/index.js ./
COPY --from=builder /app/node_modules ./node_modules

CMD ["bun", "run", "index.js"]

Including Additional Files

Configuration Files

COPY config ./config
COPY templates ./templates

Binary Tools

# Install additional tools
RUN apt-get update && apt-get install -y \
    jq \
    yq \
    && rm -rf /var/lib/apt/lists/*

COPY . .

Environment Variables

# Set environment variables
ENV NODE_ENV=production
ENV LOG_LEVEL=info

# Runtime environment (can be overridden)
ENV PROCESSOR_DEBUG=false

Best Practices

1. Use Specific Versions

# Good: Specific version
FROM oven/bun:1.3.8

# Avoid: Latest (unpredictable)
FROM oven/bun:latest

Choose a version that matches your development environment. Current stable versions include 1.3.8 and later.

2. Minimize Layers

# Good: Combined commands
RUN apt-get update && apt-get install -y \
    curl \
    jq \
    && rm -rf /var/lib/apt/lists/*

# Avoid: Multiple layers
RUN apt-get update
RUN apt-get install -y curl
RUN apt-get install -y jq

3. Use .dockerignore

Create a .dockerignore file:

node_modules
.git
.gitignore
*.md
tests/
.env*

4. Copy Lockfile Separately

# Good: Separate COPY commands
COPY package.json .
COPY bun.lockb .
RUN bun install

# Avoid: Glob pattern (may silently skip lockfile)
COPY package.json bun.lockb* ./

Processors should be deterministic. Always include your lockfile to ensure consistent dependency versions across builds.

Port Configuration

Processors communicate over port 5551 by default. The SDKs handle this automatically for Bun and Python:

Bun/Node.js SDK: Listens on port 5551 automatically
Python SDK: Listens on port 5551 automatically
.NET SDK: Requires explicit configuration: ENV ASPNETCORE_URLS=http://+:5551

Full Example

#syntax=docker/dockerfile:1

# Build stage
FROM oven/bun:1.3.8-alpine AS builder

WORKDIR /app

# Install build dependencies
COPY package.json .
COPY bun.lockb .
RUN bun install

# Build
COPY tsconfig.json ./
COPY src ./src
COPY index.ts ./
RUN bun build index.ts --outdir=dist --target=bun --minify

# Runtime stage
FROM oven/bun:1.3.8-alpine

WORKDIR /app

# Required label
LABEL cyanprint.dev=true
LABEL org.opencontainers.image.source=https://github.com/org/my-processor
LABEL org.opencontainers.image.description="My custom processor"

# Copy built files
COPY --from=builder /app/dist/index.js ./

# Production dependencies only
COPY package.json .
COPY bun.lockb .
RUN bun install --production

# Set environment
ENV NODE_ENV=production
ENV LOG_LEVEL=info

CMD ["bun", "run", "index.js"]

Project Structure - File layout
Push to Registry - Publishing
First Processor - Tutorial

Processor Dockerfile

On this page