Configuração Docker

Executar o Artisan dentro do Docker requer um binário Chrome ou Chromium no container. Este guia cobre padrões de Dockerfile prontos para produção, configuração do Compose, considerações de segurança e suporte a fontes.

Dockerfile

Mínimo (baseado em Debian)

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 . .

Baseado em Alpine (Imagem Menor)

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

Flags do Chrome para Docker

O Chrome em um container precisa de flags específicas para funcionar de forma confiável. Passe-as ao criar o 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

A flag --no-sandbox desabilita o sandbox de processo do Chrome. Em produção, prefira manter o sandbox habilitado e conceder ao container a capability SYS_ADMIN ou usar um perfil seccomp personalizado.

Considerações de Segurança

Opção A: Manter o Sandbox (Recomendado)

Adicione SYS_ADMIN ao container e omita --no-sandbox.

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

Você pode encontrar o perfil seccomp mínimo para o Chrome na documentação do projeto Chromium.

Opção B: Usuário Não-Root

Execute o Chrome como um usuário dedicado sem privilégios dentro do 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

Opção C: Sistema de Arquivos Somente Leitura

Monte o sistema de arquivos raiz como somente leitura e forneça tmpfs gravável para o Chrome.

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

Limites de Memória

O Chrome pode consumir memória significativa, especialmente ao renderizar páginas complexas. Defina limites do container e monitore o uso.

Complexidade da Página	Memória Recomendada
Texto simples (1--5 páginas)	256 MB
Tabelas e imagens (5--20 páginas)	512 MB
Layouts complexos, gráficos, JS (20+ páginas)	1 GB+

Se o Chrome ficar sem memória, ele encerra com código 137 (OOM killed). A RenderException do Artisan encapsula isso com uma mensagem descritiva.

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

Instalação de Fontes

Imagens Docker vêm com fontes mínimas. Instale fontes adicionais para renderização adequada de scripts não-latinos e tipografia da marca.

Fontes do Sistema

# 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

Fontes Personalizadas

Copie arquivos de fonte para o container e registre-os com fontconfig.

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

Web Fonts

O Chrome no Artisan pode buscar web fonts @font-face no momento da renderização, assim como um navegador normal. Nenhuma configuração extra é necessária, mas certifique-se de que o container tenha acesso de rede ao CDN de fontes.

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

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

Health Check

Adicione um health check que verifica se o Chrome está operacional.

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

Exemplo Completo de Produção

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"]

Próximos Passos

• Recursos Avançados -- Configuração do Chrome, connection pooling, tratamento de erros.
• Visão Geral -- Resumo do pacote e instalação.