Dockerfiles Reference

CyanPrint templates use two Docker images: one for template execution and one for file storage.

Overview

Dockerfile	Purpose	Location
`Dockerfile`	Executes template logic	`cyan/Dockerfile`
`blob.Dockerfile`	Stores source files	Project root

Template Dockerfile

Defines the environment where template logic runs.

Basic Template

FROM oven/bun:1.1.31-alpine

WORKDIR /app

LABEL cyanprint.dev=true

# Copy and install dependencies
COPY package.json ./
COPY bun.lockb ./
RUN bun install

# Copy template source
COPY . .

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

With Additional Tools

FROM oven/bun:1.1.31-alpine

LABEL cyanprint.dev=true

# Install additional tools
RUN apk add --no-cache git curl

WORKDIR /app

# Dependencies
COPY package.json ./
COPY bun.lockb ./
RUN bun install

# Source
COPY . .

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

Multi-Stage Build (.NET Example)

For SDKs that require compilation, use multi-stage builds:

# Build stage
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS builder

WORKDIR /build
COPY *.csproj ./
RUN dotnet restore
COPY . ./
RUN dotnet publish -c Release -o out

# Runtime stage
FROM mcr.microsoft.com/dotnet/runtime:8.0

WORKDIR /app
LABEL cyanprint.dev=true

COPY --from=builder /build/out/ ./

CMD ["dotnet", "Template.dll"]

Template Dockerfiles are built from within the cyan/ directory. This means COPY paths are relative to cyan/, not the repository root. The SDK hosts its API on port 5550 for /init and /validate endpoints.

blob.Dockerfile

Stores template files for efficient transfer to the client. The blob image packages template files and extracts them to /workspace/cyanprint/ on the client.

Production Blob (Recommended)

Uses tar archival for efficient transfer:

FROM alpine:3.21 AS base

WORKDIR /src

# Copy the cyan directory contents
COPY . ./

# Remove unnecessary files and create archive
RUN rm -rf cyan && \
    mkdir -p /cyanprint/artifact && \
    tar -czvf /cyanprint/artifact/cyan.tar.gz /src/

# Runtime stage - extracts archive to workspace
FROM alpine:3.21

# On container start, extract files to the expected path
CMD [ "tar", "-xzf", "/cyanprint/artifact/cyan.tar.gz", "-C", "/workspace/cyanprint", "--strip-components=1" ]

The blob image must extract files to /workspace/cyanprint/ for the CyanPrint runtime to access them correctly.

Minimal Blob

For simple templates with few files:

FROM alpine:3.21

COPY . /cyanprint/

Best Practices

Template Dockerfile

Use specific versions

# Good: Specific version
FROM oven/bun:1.1.31-alpine

# Bad: Latest (unpredictable)
FROM oven/bun:alpine

Minimize layers

# Good: Combined commands
RUN apk add --no-cache git curl && \
    bun install -g typescript

# Bad: Multiple layers
RUN apk add --no-cache git
RUN apk add --no-cache curl
RUN bun install -g typescript

Always include the required label

# Required for CyanPrint to identify template images
LABEL cyanprint.dev=true

Use .dockerignore

Create .dockerignore to exclude unnecessary files:

node_modules
.git
*.log
.env
nix
.direnv
flake.nix
flake.lock
*.md
.vscode
.idea

Blob Dockerfile

Keep it minimal

# Good: Minimal image with tar archive
FROM alpine:3.21 AS base
WORKDIR /src
COPY . ./
RUN mkdir -p /cyanprint/artifact && \
    tar -czvf /cyanprint/artifact/cyan.tar.gz /src/

# Bad: Unnecessary bloat with runtime
FROM oven/bun:1.1.31-alpine
RUN bun install
COPY . ./

Use consistent extraction paths

Always extract to /workspace/cyanprint/ for consistency with the CyanPrint runtime.

Building Images

The template Dockerfile is named Dockerfile and located in the cyan/ directory. The blob Dockerfile is named blob.Dockerfile and located at the project root. Template images are built from within the cyan/ directory context.

Development Build

# Build template locally
docker build -t my-template:dev ./cyan

# Build blob locally (from project root)
docker build -f blob.Dockerfile -t my-template-blob:dev .

Production Build (Multi-Arch)

# Build and push template
docker buildx build --platform linux/amd64,linux/arm64 \
  -t myorg/my-template:1.0.0 \
  --push ./cyan

# Build and push blob (from project root)
docker buildx build --platform linux/amd64,linux/arm64 \
  -f blob.Dockerfile \
  -t myorg/my-template-blob:1.0.0 \
  --push .

Image Sizes

Optimize for smaller images:

Base Image	Size	Use Case
`alpine`	~5MB	Blob images
`oven/bun:alpine`	~100MB	Template execution (Bun SDK)
`oven/bun:slim`	~150MB	Template execution (need glibc)
`python:slim`	~150MB	Template execution (Python SDK)
`mcr.microsoft.com/dotnet/runtime`	~80MB	Template execution (.NET SDK)

Debugging

To debug Dockerfile issues locally:

# Run template container interactively
docker run -it --rm -p 5550:5550 my-template:dev sh

# Verify working directory and files
ls -la /app

# Test the SDK endpoints
curl http://localhost:5550/init

# Run blob container and verify extraction paths
docker run -it --rm my-template-blob:dev sh
ls -la /cyanprint/

Push to Registry - Publishing templates
Project Structure - Template organization
cyan.yaml Reference - Metadata configuration

Dockerfiles Reference

On this page