Configuration d'un navigateur headless sur Ubuntu : guide complet pour serveur

Introduction

Executer BotBrowser sur un serveur Ubuntu headless est la base de la plupart des deploiements en production. Les serveurs n'ont pas d'ecran physique, les pilotes GPU different des systemes desktop, et Chrome a des dependances de bibliotheques specifiques qui ne sont pas installees par defaut sur les images serveur minimales. Obtenir ces details correctement fait la difference entre un environnement de production stable et des plantages intermittents difficiles a diagnostiquer.

Ce guide couvre tout, de l'installation des dependances systeme a la configuration de Xvfb (X Virtual Frame Buffer), en passant par la mise en place de services systemd pour la persistance et l'execution de BotBrowser avec Playwright ou Puppeteer en mode headless. A la fin, vous disposerez d'un serveur Ubuntu fiable qui execute des instances BotBrowser sans surveillance.

Pourquoi la configuration de serveur headless est importante

Les environnements desktop gerent automatiquement la gestion de l'affichage, l'initialisation GPU et le rendu des polices. Les environnements serveur eliminent tout cela. Une installation minimale d'Ubuntu Server ne dispose pas des bibliotheques partagees dont Chrome a besoin pour le rendu, du serveur d'affichage X11 que meme Chrome headless s'attend a trouver, ni des packages de polices qui affectent le rendu du texte.

Sans configuration correcte, vous rencontrerez des erreurs allant des plus evidentes ("cannot open display") aux plus subtiles (segfaults lors du rendu WebGL, sortie canvas vide, ou familles de polices manquantes dans les verifications d'empreinte). Chacun de ces problemes peut silencieusement degrader votre protection d'empreinte sans aucun message d'erreur clair.

La variable d'environnement DISPLAY est particulierement importante. Meme lors de l'execution de Chrome en mode headless, Chrome initialise quand meme certains sous-systemes lies a l'affichage. Sur Ubuntu, DISPLAY=:10.0 doit etre defini et Xvfb doit etre en cours d'execution sur cet affichage. Ignorer cette etape conduit a des plantages ou un rendu degrade qui affecte la coherence de l'empreinte.

Contexte technique

Xvfb (X Virtual Frame Buffer)

Xvfb fournit un serveur d'affichage virtuel qui implemente le protocole X11 sans necessiter de materiel d'affichage physique. Chrome se connecte a Xvfb comme s'il s'agissait d'un veritable ecran, completant correctement son initialisation de rendu.

Parametres de configuration cles :

• Numero d'affichage (:10) : un identifiant arbitraire. Utiliser :10 evite les conflits avec :0 qui peut etre utilise par les installations desktop.
• Specification d'ecran (1920x1080x24) : largeur, hauteur et profondeur de couleur. Une profondeur de couleur de 24 bits est requise pour un rendu precis. Des profondeurs inferieures causent des bandes de couleur dans les captures d'ecran et une sortie canvas incorrecte.
• Variable d'environnement DISPLAY (DISPLAY=:10.0) : doit etre definie pour chaque processus qui lance Chrome, y compris les scripts Node.js et les scripts shell.

Dependances systeme de Chrome

Chrome depend de dizaines de bibliotheques partagees pour le rendu, l'audio, le reseau et l'accessibilite. Sur une installation Ubuntu desktop, la plupart d'entre elles sont presentes. Sur une installation serveur, vous devez les installer explicitement.

Les categories critiques sont :

• Graphiques : libdrm2, libgbm1, libxcomposite1, libxdamage1, libxrandr2 pour la composition d'affichage
• Toolkit UI : libgtk-3-0, libatk-bridge2.0-0, libatk1.0-0 pour l'accessibilite et le rendu des widgets
• Securite : libnss3, libnspr4 pour TLS et la gestion des certificats
• Audio : libasound2 pour l'initialisation du sous-systeme audio (meme sans lecture audio)
• Polices : fonts-liberation pour la disponibilite des polices de base
• Integration desktop : xdg-utils pour la gestion des types MIME

<svg viewBox="0 0 700 300" xmlns="http://www.w3.org/2000/svg" style={{maxWidth: '100%', height: 'auto'}}> Headless Server Architecture BotBrowser Chrome + Profile Headless Mode Xvfb :10 Virtual Display 1920x1080x24 System Libs GTK, NSS, GBM Fonts, Audio Ubuntu 22.04 LTS (Headless) DISPLAY=:10.0 set in environment

Approches courantes et limites

Executer sans Xvfb

Certains guides suggerent d'executer Chrome headless sans Xvfb. Bien que le flag --headless de Chrome ne necessite pas strictement un affichage X pour le chargement de pages basique, certaines operations de rendu, chemins d'initialisation GPU et routines d'enumeration de polices se comportent differemment sans serveur d'affichage. Le resultat est un rendu incoherent qui affecte la stabilite de l'empreinte.

Les profils BotBrowser definissent des proprietes d'affichage specifiques. Sans Xvfb, le navigateur peut se replier sur des chemins de rendu logiciel qui produisent des sorties canvas et WebGL differentes de celles specifiees par le profil. Executez toujours Xvfb.

Packages de polices manquants

Ubuntu Server est livre avec un support de polices minimal. Chrome peut rendre du texte sans polices supplementaires, mais la liste des polices disponibles et les metriques de rendu ne correspondront pas a ce qu'un veritable utilisateur desktop aurait. Cela cree une incoherence d'empreinte. Le moteur de polices multi-plateformes de BotBrowser attenue ce probleme en integrant les polices du profil, mais avoir des polices systeme disponibles comme repli ameliore la coherence du rendu.

Profondeur d'affichage incorrecte

Utiliser Xvfb :10 -screen 0 1920x1080x16 (couleur 16 bits) au lieu de 24 bits cause des problemes de profondeur de couleur. Le rendu canvas utilise moins de canaux de couleur, produisant des donnees de pixels differentes et des hashes d'empreinte differents. Utilisez toujours une profondeur de 24 bits.

Executer en tant que root sans flags sandbox

Le sandbox de Chrome necessite des capacites kernel specifiques. Dans les conteneurs Docker ou lors de l'execution en tant que root, le sandbox echoue silencieusement ou plante. Utilisez --disable-setuid-sandbox dans ces environnements.

L'approche de BotBrowser

BotBrowser est concu pour les deploiements sur serveur headless. Son systeme de profils multi-plateformes garantit qu'un profil Windows charge sur un serveur Linux produit la meme empreinte que sur une veritable machine Windows. Le moteur de polices integre rend le texte en utilisant les donnees de polices du profil independamment des polices installees sur le serveur. Les valeurs d'empreinte GPU proviennent du profil, pas du GPU reel du serveur.

Cela signifie que le materiel du serveur ne fuit pas dans l'empreinte. Un VPS cloud a 5 dollars et un serveur dedie a 500 dollars produisent des resultats identiques avec le meme profil.

Cependant, le serveur doit toujours fournir l'infrastructure de rendu attendue par Chrome. BotBrowser ne peut pas s'initialiser correctement sans les bibliotheques systeme listees ci-dessus et un serveur d'affichage en cours d'execution.

Configuration et utilisation

Etape 1 : Installer les dependances systeme

sudo apt-get update && sudo apt-get install -y \
  wget ca-certificates fonts-liberation \
  libasound2 libatk-bridge2.0-0 libatk1.0-0 \
  libcups2 libdbus-1-3 libdrm2 libgbm1 \
  libgtk-3-0 libnspr4 libnss3 \
  libxcomposite1 libxdamage1 libxrandr2 \
  xdg-utils xvfb

Pour Ubuntu 24.04, certains noms de paquets ont change. Si vous rencontrez des erreurs, executez :

sudo apt-get install -y \
  libasound2t64 libatk-bridge2.0-0 libatk1.0-0 \
  libcups2t64 libgbm1 libgtk-3-0t64 \
  libnss3 libxcomposite1 libxdamage1 \
  libxrandr2 xvfb fonts-liberation xdg-utils

Etape 2 : Demarrer Xvfb

Pour un test immediat :

Xvfb :10 -screen 0 1920x1080x24 &
export DISPLAY=:10.0

Pour la production, creez un service systemd :

# /etc/systemd/system/xvfb.service
[Unit]
Description=X Virtual Frame Buffer
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/Xvfb :10 -screen 0 1920x1080x24
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Activez et demarrez le service :

sudo systemctl daemon-reload
sudo systemctl enable xvfb
sudo systemctl start xvfb

Etape 3 : Installer BotBrowser

# Telecharger la derniere version
wget -O botbrowser.tar.gz \
  https://github.com/botswin/BotBrowser/releases/latest/

# Extraire vers /opt
sudo mkdir -p /opt/botbrowser
sudo tar -xzf botbrowser.tar.gz -C /opt/botbrowser/
sudo chmod +x /opt/botbrowser/chrome

# Verifier l'installation
DISPLAY=:10.0 /opt/botbrowser/chrome --version

Etape 4 : Telecharger les profils

sudo mkdir -p /opt/profiles
git clone https://github.com/botswin/BotBrowser.git /opt/profiles

Etape 5 : Test de lancement

DISPLAY=:10.0 /opt/botbrowser/chrome \
  --bot-profile="/opt/profiles/windows-chrome-131.enc" \
  --headless \
  --remote-debugging-port=9222 &

Verifiez que le navigateur fonctionne :

curl -s http://localhost:9222/json/version | python3 -m json.tool

Etape 6 : Integration Playwright

npm install playwright-core

const { chromium } = require('playwright-core');

(async () => {
  const browser = await chromium.launch({
    executablePath: '/opt/botbrowser/chrome',
    args: [
      '--disable-setuid-sandbox',
      '--bot-profile=/opt/profiles/windows-chrome-131.enc',
      '--proxy-server=socks5://user:pass@proxy.example.com:1080',
    ],
    headless: true,
  });

  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('https://example.com');
  console.log('Title:', await page.title());
  await browser.close();
})();

Executez avec la variable d'affichage :

DISPLAY=:10.0 node script.js

Etape 7 : Service systemd pour l'automatisation

Pour des workers d'automatisation persistants :

# /etc/systemd/system/botbrowser-worker.service
[Unit]
Description=BotBrowser Automation Worker
After=xvfb.service
Requires=xvfb.service

[Service]
Type=simple
Environment=DISPLAY=:10.0
WorkingDirectory=/opt/scripts
ExecStart=/usr/bin/node /opt/scripts/worker.js
Restart=always
RestartSec=10
User=botbrowser
Group=botbrowser

[Install]
WantedBy=multi-user.target

Instances multiples

Chaque instance concurrente a besoin de son propre --user-data-dir :

for i in $(seq 1 5); do
  DISPLAY=:10.0 /opt/botbrowser/chrome \
    --bot-profile="/opt/profiles/profile-${i}.enc" \
    --user-data-dir="/tmp/bb-session-${i}" \
    --remote-debugging-port=$((9222 + i)) \
    --headless &
done

Gestion des processus avec PM2

npm install -g pm2

DISPLAY=:10.0 pm2 start worker.js --name "bb-worker-1" \
  -- --profile="/opt/profiles/profile-1.enc"

DISPLAY=:10.0 pm2 start worker.js --name "bb-worker-2" \
  -- --profile="/opt/profiles/profile-2.enc"

pm2 save
pm2 startup  # Generer le demarrage automatique systemd

Verification

Apres avoir complete la configuration, verifiez que tout fonctionne :

# Verifier que Xvfb fonctionne
systemctl status xvfb

# Verifier que l'affichage est accessible
DISPLAY=:10.0 xdpyinfo | head -5

# Verifier que les dependances Chrome sont satisfaites
ldd /opt/botbrowser/chrome | grep "not found"

# Lancer et verifier l'empreinte
DISPLAY=:10.0 node -e "
const { chromium } = require('playwright-core');
(async () => {
  const b = await chromium.launch({
    executablePath: '/opt/botbrowser/chrome',
    args: ['--bot-profile=/opt/profiles/profile.enc'],
    headless: true,
  });
  const p = await (await b.newContext()).newPage();
  const ua = await p.evaluate(() => navigator.userAgent);
  console.log('User-Agent:', ua);
  const wd = await p.evaluate(() => navigator.webdriver);
  console.log('webdriver:', wd);
  await b.close();
})();
"

La valeur de webdriver devrait etre false, et le User-Agent devrait correspondre au profil charge.

Bonnes pratiques

Definissez toujours DISPLAY=:10.0. Ajoutez-le a /etc/environment ou a vos fichiers de service pour ne jamais l'oublier. Meme Chrome headless en a besoin sur Linux.

Utilisez une profondeur de couleur de 24 bits pour Xvfb. Des profondeurs inferieures produisent une sortie de rendu incorrecte.

Surveillez l'utilisation du disque. Chrome ecrit des crash dumps et des donnees de cache dans --user-data-dir. Mettez en place une rotation des logs ou un nettoyage periodique pour eviter l'epuisement du disque.

Gardez les dependances a jour. Executez apt-get upgrade periodiquement. Les decalages de versions de bibliotheques peuvent causer des problemes de rendu subtils.

Definissez des limites de ressources. Utilisez MemoryLimit et CPUQuota de systemd pour empecher les instances incontroles de consommer toutes les ressources du serveur.

Questions frequentes

BotBrowser fonctionne-t-il sur Ubuntu 24.04 ?

Oui. Certains noms de paquets ont change (par exemple, libasound2 est devenu libasound2t64). La commande d'installation alternative de l'Etape 1 couvre ces changements.

Puis-je utiliser une resolution Xvfb plus elevee ?

Oui. Vous pouvez definir Xvfb :10 -screen 0 2560x1440x24 ou toute resolution dont vous avez besoin. Faites-la correspondre a la resolution d'ecran du profil pour de meilleurs resultats.

Ai-je besoin d'un GPU sur le serveur ?

Non. BotBrowser utilise les valeurs GPU du profil pour le reporting d'empreinte. Le GPU reel du serveur (ou son absence) n'affecte pas la sortie d'empreinte.

Pourquoi ne pas simplement utiliser --headless=new sans Xvfb ?

Le nouveau mode headless de Chrome initialise quand meme des sous-systemes d'affichage. Sans Xvfb, certains chemins de rendu se replient sur le mode logiciel uniquement, ce qui peut produire des sorties canvas et WebGL differentes. Pour des resultats d'empreinte coherents, executez toujours Xvfb.

Combien d'instances puis-je executer par serveur ?

Cela depend des ressources du serveur. Chaque instance Chrome utilise 200-500 Mo de RAM. Un serveur avec 16 Go de RAM peut confortablement executer 20-30 instances avec de la marge pour le systeme d'exploitation et les services de support. Surveillez l'utilisation memoire et reduisez la concurrence si vous observez de l'activite swap.

Comment verifier les bibliotheques manquantes ?

Executez ldd /opt/botbrowser/chrome | grep "not found". Toutes les bibliotheques listees comme "not found" doivent etre installees. Utilisez apt-file search libname.so pour trouver le paquet qui fournit une bibliotheque specifique.

Puis-je executer BotBrowser sur des serveurs Ubuntu ARM ?

BotBrowser fournit des builds Linux x86_64. Le support ARM depend de la version specifique. Consultez la page des releases GitHub pour les architectures disponibles.

Comment mettre a jour BotBrowser ?

Telechargez la derniere version et extrayez-la par-dessus l'installation existante. Aucun changement de configuration n'est necessaire. Mettez a jour les profils depuis le depot BotBrowser Profiles en meme temps pour correspondre a la nouvelle version du navigateur.

Resume

La configuration de BotBrowser sur un serveur Ubuntu headless necessite l'installation des dependances systeme, la configuration de Xvfb et une gestion correcte des variables d'environnement. Une fois configure, le serveur fournit une base stable pour executer n'importe quel nombre d'instances BotBrowser avec une protection d'empreinte coherente.

Pour les deploiements conteneurises, consultez le Guide de deploiement Docker. Pour l'optimisation des performances a grande echelle, consultez Optimiser les performances de BotBrowser en production. Pour les combinaisons de flags CLI, consultez les Recettes CLI.