Configurer le moteur de rendu Chrome pour NextPDF Artisan

En bref

Le pont lance et pilote un processus local Chrome/Chromium via chrome-php/chrome. Cette page prépare cet environnement d’exécution pour que les rendus se terminent correctement, et couvre les choix liés aux conteneurs et au sandbox.

Comment le pont dialogue avec Chrome

BrowserPool construit une chrome-php/chromeBrowserFactory (le cas échéant avec un chemin de binaire explicite) et lance Chrome avec un ensemble fixe de drapeaux : headless: true, keepAlive: true, windowSize: [1200, 800], sendSyncDefaultTimeout: renderTimeout * 1000, ainsi que les drapeaux personnalisés indiqués sur la page /integrations/artisan/configuration/. Le pont pilote ensuite le processus lancé via le Chrome DevTools Protocol. Il ne se connecte pas à une instance de Chrome lancée séparément via un port de débogage distant : il n’y a donc aucun point d’accès réseau à exposer ni à authentifier. Chrome s’exécute en tant que processus enfant du worker PHP. Le test tests/Unit/Artisan/BrowserPoolTest.php::getBrowserCreatesAndReusesInstanceWithExpectedOptions vérifie précisément ces options de lancement.

Mettre en place le binaire

Installe une version de Chrome ou Chromium que l’utilisateur du worker peut exécuter :

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# Alpine (containers)
apk add --no-cache chromium nss freetype harfbuzz ttf-freefont

Vérifie que le binaire s’exécute en mode headless sous l’utilisateur du worker :

chromium --headless --dump-dom about:blank

Un code de sortie 0 avec un DOM vide confirme que le binaire et ses bibliothèques partagées sont présents. Un code de sortie non nul correspond à l’échec que le pont remonte sous forme de ChromeRenderException. Corrige d’abord ce problème ici.

Pointer le pont vers le binaire

La détection automatique (comportement par défaut de chrome-php/chrome) fonctionne lorsqu’un binaire est présent dans un chemin standard. Pour un comportement déterministe en production, définis ce chemin explicitement :

$config = new ChromeRendererConfig(
    chromeBinaryPath: '/usr/bin/chromium',
);

ou via une configuration sous forme de tableau :

$config = ChromeRendererConfig::fromArray([
    'chrome_binary' => '/usr/bin/chromium',
]);

Mise en place du conteneur et décision concernant le sandbox

Dans un conteneur, le sandbox OS de Chrome ne peut souvent pas s’initialiser en tant que root / PID 1 sans capacités supplémentaires du noyau. Tu as deux options :

1. Conserve le sandbox (recommandé). Exécute le worker sous un utilisateur non-root et accorde au conteneur les capacités dont le sandbox de Chrome a besoin (couramment SYS_ADMIN, ou un profil seccomp qui autorise la création d’espaces de noms utilisateur). Cela préserve l’isolation des processus de Chrome.
2. Désactive le sandbox. Définis no_sandbox: true. Chrome se lance avec --no-sandbox. Cela supprime le sandbox d’isolation des processus de Chrome — une réduction réelle du confinement, pas un drapeau cosmétique. Ne l’utilise que lorsque le sandbox ne peut pas être activé, exécute Chrome sous un utilisateur non-root à l’intérieur d’un conteneur contraint, et considère ce déploiement comme exigeant un niveau de confiance plus élevé envers les entrées. Les protections réseau du pont (CSP + blocage CDP) restent en vigueur dans les deux cas, mais elles ne remplacent pas l’isolation des processus. Cela s’aligne sur les recommandations de moindre privilège et d’isolation de l’OWASP ASVS pour le rendu de contenu non fiable.

La description complète de cette frontière — ce que le sandbox protège et ne protège pas — se trouve sur la page /integrations/artisan/security-and-operations/. Cette page n’affirme pas que désactiver le sandbox est sûr.

Conteneur de référence

FROM php:8.4-cli
RUN apt-get update && apt-get install -y --no-install-recommends \
        chromium fonts-liberation \
    && rm -rf /var/lib/apt/lists/*
RUN useradd -m -u 10001 worker
USER worker
ENV CHROME_BINARY=/usr/bin/chromium
# Set CHROME_NO_SANDBOX=1 only if the sandbox cannot be enabled in your runtime.

Exécute le worker en tant que worker (uid 10001), pas en root. Le pont applique déjà le drapeau --disable-dev-shm-usage, qui évite les crashs dus à un /dev/shm trop petit, fréquents dans les conteneurs sans réglage supplémentaire.

Polices

Le pont bloque le téléchargement des polices distantes (--disable-remote-fonts et CSP). Installe les polices nécessaires au niveau de l’OS, ou intègre-les sous forme d’URI data: dans des règles @font-face à l’intérieur de defaultCss ou du HTML. La sortie CJK nécessite un paquet de polices CJK (par exemple fonts-noto-cjk) installé dans l’image.

Sonde de santé

Utilise cette sonde autonome pour tester le chemin complet du pont sans passer par l’application hôte :

chrome-health.php

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeHtmlRenderer;
use NextPDF\Artisan\ChromeRendererConfig;

require __DIR__ . '/vendor/autoload.php';

$renderer = new ChromeHtmlRenderer(
    ChromeRendererConfig::fromArray([
        'chrome_binary' => getenv('CHROME_BINARY') ?: null,
        'no_sandbox'    => (bool) getenv('CHROME_NO_SANDBOX'),
    ]),
);

$result = $renderer->render('<p>ok</p>', 200.0, 0.0);
fwrite(STDOUT, strlen($result->getPdfData()) > 0 ? "CHROME_OK\n" : "CHROME_EMPTY\n");
$renderer->close();

CHROME_OK confirme le lancement, le rendu et l’importation. Si une exception est levée, elle indique l’échec précis. Fais-la correspondre aux cas de la page /integrations/artisan/troubleshooting/. Intègre cette sonde comme vérification de disponibilité dans les déploiements orchestrés.

Notes sur l’isolation des ressources

• Exécute Chrome sous un utilisateur non-root dédié.
• Applique une limite de mémoire au niveau de l’hôte ; le pont borne la croissance avec un redémarrage tous les 100 rendus, mais un plafond côté hôte reste nécessaire.
• Associe render_timeout à un budget de requête en amont pour tout chemin accessible à des entrées non fiables.
• N’expose pas de port de débogage distant de Chrome. Le pont n’en utilise pas et un port CDP ouvert est un canal de contrôle non authentifié.

Modes de défaillance et dépannage

Symptôme	Cause probable	Où vérifier
ChromeNotAvailableException	chrome-php/chrome non installé	/integrations/artisan/install/
ChromeRenderException au premier rendu	Binaire manquant / le sandbox ne peut pas s’initialiser	Cette page ; /integrations/artisan/troubleshooting/
PDF vide	Aucune boîte visible / crash de Chrome	/integrations/artisan/troubleshooting/
Images distantes vides	Réseau bloqué par conception	/integrations/artisan/security-and-operations/
Pic de latence périodique	Redémarrage tous les 100 rendus	/integrations/artisan/production-usage/

Voir aussi

• /integrations/artisan/install/
• /integrations/artisan/configuration/
• /integrations/artisan/security-and-operations/
• /integrations/artisan/troubleshooting/
• /integrations/artisan/production-usage/