Docker Setup

Running Artisan inside Docker requires a Chrome or Chromium binary in the container. This guide covers production-ready Dockerfile patterns, Compose configuration, security considerations, and font support.

Dockerfile

Minimal (Debian-based)

FROM php:8.3-cli

# Install Chromium and required libraries
RUN apt-get update && apt-get install -y --no-install-recommends \
    chromium \
    fonts-liberation \
    libappindicator3-1 \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libcups2 \
    libdbus-1-3 \
    libdrm2 \
    libgbm1 \
    libnspr4 \
    libnss3 \
    libx11-xcb1 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    xdg-utils \
    && rm -rf /var/lib/apt/lists/*

# Set Chrome path for Artisan auto-detection
ENV CHROME_PATH=/usr/bin/chromium

# Install Composer dependencies
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader

COPY . .

Alpine-based (Smaller Image)

FROM php:8.3-cli-alpine

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

ENV CHROME_PATH=/usr/bin/chromium-browser

COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader

COPY . .

Docker Compose

services:
  app:
    build: .
    volumes:
      - ./output:/app/output
    environment:
      CHROME_PATH: /usr/bin/chromium
    deploy:
      resources:
        limits:
          memory: 1G
        reservations:
          memory: 512M
    # Required for Chrome sandboxing in Docker
    security_opt:
      - seccomp=unconfined
    cap_add:
      - SYS_ADMIN

Chrome Flags for Docker

Chrome in a container needs specific flags to run reliably. Pass them when creating the renderer.

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

$renderer = HtmlRenderer::create(
    chromeFlags: [
        '--no-sandbox',              // required unless you configure seccomp
        '--disable-setuid-sandbox',  // secondary sandbox bypass
        '--disable-gpu',             // no GPU in containers
        '--disable-dev-shm-usage',   // write to /tmp instead of /dev/shm
        '--disable-software-rasterizer',
        '--single-process',          // reduce memory for simple renders
    ],
);

WARNING

The --no-sandbox flag disables Chrome's process sandbox. In production, prefer keeping the sandbox enabled and granting the container SYS_ADMIN capability or using a custom seccomp profile instead.

Security Considerations

Option A: Keep the Sandbox (Recommended)

Add SYS_ADMIN to the container and omit --no-sandbox.

services:
  app:
    cap_add:
      - SYS_ADMIN
    security_opt:
      - seccomp=chrome-seccomp.json

You can find the minimal seccomp profile for Chrome in the Chromium project documentation.

Option B: Non-Root User

Run Chrome as a dedicated unprivileged user inside the container.

RUN groupadd -r artisan && useradd -r -g artisan -G audio,video artisan \
    && mkdir -p /home/artisan/Downloads \
    && chown -R artisan:artisan /home/artisan

USER artisan

Option C: Read-Only Filesystem

Mount the root filesystem as read-only and provide writable tmpfs for Chrome.

services:
  app:
    read_only: true
    tmpfs:
      - /tmp
      - /home/artisan/.config

Memory Limits

Chrome can consume significant memory, especially when rendering complex pages. Set container limits and monitor usage.

Page Complexity	Recommended Memory
Simple text (1--5 pages)	256 MB
Tables and images (5--20 pages)	512 MB
Complex layouts, charts, JS (20+ pages)	1 GB+

If Chrome runs out of memory, it exits with code 137 (OOM killed). The Artisan RenderException wraps this with a descriptive message.

// Fail fast with a tight timeout to avoid memory runaway
$options = RenderOptions::create()->setTimeout(15000);

Font Installation

Docker images ship with minimal fonts. Install additional fonts for proper rendering of non-Latin scripts and branded typography.

System Fonts

# CJK fonts (Chinese, Japanese, Korean)
RUN apt-get update && apt-get install -y \
    fonts-noto-cjk \
    fonts-noto-cjk-extra

# Arabic, Hebrew, Devanagari
RUN apt-get install -y \
    fonts-noto-core \
    fonts-noto-extra

# Google Fonts (e.g., Inter, Roboto)
RUN apt-get install -y fonts-inter

Custom Fonts

Copy font files into the container and register them with fontconfig.

COPY ./fonts/*.ttf /usr/share/fonts/custom/
RUN fc-cache -fv

Web Fonts

Chrome in Artisan can fetch @font-face web fonts at render time, just like a regular browser. No extra configuration is needed, but ensure the container has network access to the font CDN.

@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap');

body {
    font-family: 'Inter', sans-serif;
}

Health Check

Add a health check that verifies Chrome is operational.

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
    CMD chromium --headless=new --disable-gpu --no-sandbox \
        --dump-dom about:blank > /dev/null 2>&1 || exit 1

Complete Production Example

FROM php:8.3-cli-bookworm AS base

# System dependencies + Chromium
RUN apt-get update && apt-get install -y --no-install-recommends \
    chromium \
    fonts-liberation \
    fonts-noto-cjk \
    libnss3 libgbm1 libatk-bridge2.0-0 \
    && rm -rf /var/lib/apt/lists/*

ENV CHROME_PATH=/usr/bin/chromium

# Non-root user
RUN groupadd -r artisan && useradd -r -g artisan artisan \
    && mkdir -p /home/artisan && chown artisan:artisan /home/artisan

WORKDIR /app

COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader

COPY --chown=artisan:artisan . .

USER artisan

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
    CMD chromium --headless=new --no-sandbox --dump-dom about:blank > /dev/null 2>&1

CMD ["php", "artisan", "render:process"]

Next Steps

• Advanced Features -- Chrome configuration, connection pooling, error handling.
• Overview -- Package summary and installation.