Setup Docker

Eseguire Artisan dentro Docker richiede un binario Chrome o Chromium nel container. Questa guida copre pattern Dockerfile production-ready, configurazione Compose, considerazioni sicurezza e supporto font.

Dockerfile

Minimale (Basato su Debian)

FROM php:8.3-cli

# Installa Chromium e librerie richieste
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/*

# Imposta percorso Chrome per auto-rilevamento Artisan
ENV CHROME_PATH=/usr/bin/chromium

# Installa dipendenze Composer
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader

COPY . .

Basato su Alpine (Immagine Più Piccola)

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
    # Richiesto per sandboxing Chrome in Docker
    security_opt:
      - seccomp=unconfined
    cap_add:
      - SYS_ADMIN

Flag Chrome per Docker

Chrome in un container necessita flag specifici per funzionare affidabilmente. Passali quando crei il renderer.

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;

$renderer = HtmlRenderer::create(
    chromeFlags: [
        '--no-sandbox',              // richiesto a meno che configuri seccomp
        '--disable-setuid-sandbox',  // bypass sandbox secondario
        '--disable-gpu',             // no GPU in container
        '--disable-dev-shm-usage',   // scrivi su /tmp invece di /dev/shm
        '--disable-software-rasterizer',
        '--single-process',          // riduci memoria per rendering semplici
    ],
);

WARNING

Il flag --no-sandbox disabilita la sandbox processo Chrome. In produzione, preferisci mantenere la sandbox abilitata e garantire al container la capability SYS_ADMIN o usare un profilo seccomp personalizzato invece.

Considerazioni Sicurezza

Opzione A: Mantieni la Sandbox (Raccomandato)

Aggiungi SYS_ADMIN al container e ometti --no-sandbox.

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

Puoi trovare il profilo seccomp minimale per Chrome nella documentazione progetto Chromium.

Opzione B: Utente Non-Root

Esegui Chrome come utente dedicato non privilegiato dentro il 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

Opzione C: Filesystem Read-Only

Monta il filesystem root come read-only e fornisci tmpfs scrivibile per Chrome.

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

Limiti Memoria

Chrome può consumare memoria significativa, specialmente quando renderizza pagine complesse. Imposta limiti container e monitora utilizzo.

Complessità Pagina	Memoria Raccomandata
Testo semplice (1--5 pagine)	256 MB
Tabelle e immagini (5--20 pagine)	512 MB
Layout complessi, grafici, JS (20+ pagine)	1 GB+

Se Chrome esaurisce la memoria, esce con codice 137 (OOM killed). La RenderException Artisan avvolge questo con un messaggio descrittivo.

// Fallisci velocemente con timeout stretto per evitare runaway memoria
$options = RenderOptions::create()->setTimeout(15000);

Installazione Font

Le immagini Docker vengono fornite con font minimali. Installa font aggiuntivi per rendering corretto di script non-latini e tipografia branded.

Font Sistema

# Font CJK (Cinese, Giapponese, Coreano)
RUN apt-get update && apt-get install -y \
    fonts-noto-cjk \
    fonts-noto-cjk-extra

# Arabo, Ebraico, Devanagari
RUN apt-get install -y \
    fonts-noto-core \
    fonts-noto-extra

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

Font Personalizzati

Copia file font nel container e registrali con fontconfig.

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

Web Font

Chrome in Artisan può recuperare web font @font-face al momento del rendering, proprio come un browser normale. Non è necessaria configurazione extra, ma assicurati che il container abbia accesso rete al CDN font.

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

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

Health Check

Aggiungi un health check che verifica Chrome sia operativo.

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

Esempio Produzione Completo

FROM php:8.3-cli-bookworm AS base

# Dipendenze sistema + 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

# Utente non-root
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"]

Prossimi Passi

• Funzionalità Avanzate -- Configurazione Chrome, connection pooling, gestione errori.
• Overview -- Riepilogo pacchetto e installazione.