BotBrowser headless en servidores Ubuntu

BotBrowser puede proporcionar un runtime controlado para cargas headless autorizadas, pero no protege el host, concede permisos ni demuestra el resultado de la aplicación. Esta guía separa la base de Ubuntu y Xvfb del comportamiento del navegador, los datos sensibles del perfil y la salud de la aplicación.

Resumen

Instala solo las bibliotecas necesarias, usa una pantalla Xvfb fija y una cuenta de servicio sin privilegios, y comprueba una tarea visible para el usuario. No guardes perfiles, credenciales, contenido de páginas ni identificadores de clientes en los registros.

Contenido

• Base del host y pantalla virtual
• Instalación y lanzamiento
• Verificación, salud y recuperación
• Control de cambios y aprobación de la versión
• Preguntas sobre hosts Ubuntu headless
• Decisión de despliegue

Base del host y pantalla virtual

Ejecutar BotBrowser en un servidor Ubuntu headless es la base de la mayoría de los despliegues de producción. Los servidores no tienen pantalla física, los controladores gráficos difieren de los de un equipo de escritorio y el navegador depende de bibliotecas del sistema que las imágenes de servidor mínimas no instalan por defecto. Resolver bien estos detalles separa un entorno estable de fallos intermitentes difíciles de diagnosticar.

Un host Ubuntu de producción necesita las bibliotecas requeridas, una política de pantalla estable, servicios de navegador supervisados y una responsabilidad clara sobre perfiles y datos de usuario. Estos requisitos se aplican a sesiones desatendidas de BotBrowser con Playwright o Puppeteer y conducen a una rutina de aprobación de la versión para cada clase de host.

Los entornos de escritorio gestionan automáticamente la pantalla, la inicialización gráfica y el renderizado de fuentes. Las imágenes de servidor mínimas omiten muchas bibliotecas compartidas y paquetes de fuentes que usan las cargas del navegador, y no ofrecen ninguna pantalla. La documentación de despliegue de BotBrowser indica que BotBrowser requiere una pantalla virtual en servidores headless, incluso en modo headless.

Una configuración incompleta puede producir fallos evidentes como "cannot open display" y otros más sutiles, como capturas en blanco, caracteres ausentes o reproducción multimedia inestable. Trata cada uno de esos resultados como una comprobación de versión fallida y corrige el host antes de usarlo en producción.

Planifica una pantalla virtual en cada host. La documentación parte de una pantalla Xvfb en :10.0 y establece que DISPLAY=:10.0 debe estar definido para cada proceso de BotBrowser. Ejecuta Xvfb en esa pantalla, define DISPLAY en cada servicio del navegador y mantén explícita la dependencia entre servicios. La pantalla no elimina la necesidad de validar: comprueba renderizado, medios y capturas representativos en cada clase de host antes de aprobar.

Xvfb (X Virtual Frame Buffer)

Xvfb es un servidor de pantalla virtual que implementa el protocolo X11 sin hardware de pantalla. BotBrowser necesita una pantalla X11 incluso en modo headless, y Xvfb la proporciona en un servidor.

Parámetros de configuración principales:

• Número de pantalla (:10): un identificador arbitrario. Usar :10 evita conflictos con :0, que pueden utilizar las instalaciones de escritorio.
• Especificación de pantalla (1920x1080x24): ancho, alto y profundidad de color. Valida la profundidad elegida con capturas y cargas de renderizado representativas.
• Variable de entorno DISPLAY (DISPLAY=:10.0): defínela para cada proceso de BotBrowser, incluidos cada unidad de servicio y cada prueba manual.

Dependencias del sistema del navegador

BotBrowser usa bibliotecas compartidas para renderizado, audio, red y accesibilidad. Una instalación de escritorio de Ubuntu suele incluir la mayoría. En una imagen de servidor mínima, instálalas de forma explícita.

Las categorías críticas son:

• Gráficos: libdrm2, libgbm1, libxcomposite1, libxdamage1, libxrandr2 para la composición de pantalla
• Kit de interfaz: libgtk-3-0, libatk-bridge2.0-0, libatk1.0-0 para accesibilidad y widgets
• Seguridad: libnss3, libnspr4 para TLS y gestión de certificados
• Audio: libasound2 para la inicialización de audio, aunque no se reproduzca sonido
• Fuentes: fonts-liberation para disponer de fuentes básicas
• Integración de escritorio: xdg-utils para el manejo de tipos MIME
• Bibliotecas de apoyo: libcups2, libdbus-1-3, libxkbcommon0, libpango-1.0-0, libpangocairo-1.0-0, libwayland-client0, libwayland-server0, libatspi2.0-0, libxss1

El paso 1 instala la lista completa. Tras la instalación, ejecuta la comprobación con ldd de la sección de verificación para detectar cualquier biblioteca que siga faltando.

Por qué el modo headless sigue necesitando una pantalla

La documentación de despliegue indica que BotBrowser requiere una pantalla X11 incluso en modo --headless, por lo que un servidor sin pantalla puede fallar con errores como "cannot open display". Trata la pantalla virtual como parte de la base del host y no como un servicio opcional.

No elimines el servicio de pantalla para ahorrar recursos. Si una versión posterior documenta otra ruta de inicio compatible, vuelve a consultar la documentación y valida esa ruta en cada clase de host antes de cambiar la base.

Paquetes de fuentes faltantes

Qué ocurre realmente sin pantalla

La sección anterior explica por qué una pantalla virtual sigue formando parte de un despliegue headless compatible. Conviene separar ese requisito de lo que hace el navegador cuando no hay pantalla, porque ambos casos producen resultados distintos y la diferencia se puede medir. Las observaciones siguientes provienen de un solo host: una imagen basada en Debian con todas las bibliotecas compartidas de Chromium resueltas, incluidas las de NSS, ATK, CUPS, GBM y ALSA, y una página de prueba fija que informa si se pudo crear un contexto WebGL.

Condición de arranque	Contexto WebGL	Renderizador informado	Socket de pantalla presente
Sin variable de pantalla	creado	SwiftShader (software)	no
La variable apunta a un servicio de pantalla virtual inactivo	no creado	ninguno	no
Sin variable, repetido dos veces	creado en ambas	SwiftShader (software)	no

La fila central es la que sorprende a los operadores. Apuntar el proceso a un número de pantalla donde no escucha ningún servidor no recurre a la representación por software; el contexto simplemente no se inicializa, y una página que depende de WebGL registra una función ausente en lugar de una más lenta. La primera y la tercera fila muestran que un arranque headless sin variable de pantalla alguna sigue representando mediante el backend de software, y por eso un contenedor sin servicio de pantalla virtual puede parecer sano para cargas de página y aun así comportarse de forma distinta a la configuración compatible.

Hay que leer el resultado, no la intención. Una comprobación de salud que solo confirma que una página cargó pasará tanto en la primera como en la segunda fila, así que no puede decir qué camino tomó el despliegue. Sondee la función de la que realmente depende y registre qué renderizador respondió; luego compárelo con la configuración que pretendía ejecutar.

Se aplican dos límites. La cadena de renderizador anterior nombra el backend de software en este host, así que describe esta imagen y no todos los servidores; un host con controlador de GPU puede informar otro adaptador. Y nada de esto sustituye la configuración compatible de la sección anterior, que combina una pantalla virtual real con el conjunto de dependencias que el despliegue necesita.

Ubuntu Server incluye un soporte tipográfico mínimo. Instala los paquetes documentados y revisa páginas representativas para detectar caracteres ausentes, etiquetas recortadas, saltos de línea distintos y paginación de documentos. Conserva el conjunto de paquetes aprobado en la imagen del servidor para que los workers comparables produzcan resultados visibles estables.

Profundidad de pantalla incorrecta

Empieza con una pantalla de 24 bits como Xvfb :10 -screen 0 1920x1080x24. Valida la profundidad elegida con flujos representativos de renderizado y capturas antes de aprobar el despliegue.

Ejecutar como root y errores de sandbox

El sandbox de Chromium puede no iniciarse cuando un servicio se ejecuta como root o dentro de un contenedor. Ejecuta el servicio con un usuario sin privilegios. Si un contenedor exige una opción de sandbox, sigue la guía de despliegue y prueba esa combinación exacta en lugar de copiar opciones entre entornos.

Perfiles, hosts y comportamiento de la versión

BotBrowser admite despliegues headless en servidores. Las propiedades de huella, como el tamaño de pantalla, las fuentes y la información de GPU, proceden del paquete de perfil seleccionado y no del hardware del servidor, mientras que el host aporta las bibliotecas del sistema y un backend gráfico. Valida la configuración completa en cada clase de host que vayas a usar.

Usa el mismo perfil aprobado, la misma versión del navegador, las mismas dependencias, el mismo backend gráfico y la misma política de lanzamiento en ejecuciones comparables. Las diferencias en controladores, bibliotecas, soporte multimedia y carga de trabajo pueden seguir cambiando el resultado visible o la capacidad.

Los servidores suelen carecer de GPU física, por lo que el renderizado usa un backend por software. La documentación compara Mesa llvmpipe mediante ANGLE GL, SwiftShader y Mesa lavapipe, y recomienda llvmpipe para la mayoría de los hosts Ubuntu. Anota la clase de host y la ruta gráfica en el registro de la versión, porque una ejecución aprobada en una clase no aprueba otra.

Instalación y lanzamiento

Paso 1: instalar dependencias del sistema

sudo apt-get update && sudo apt-get install -y \
  fonts-liberation libasound2 libatk-bridge2.0-0 \
  libatk1.0-0 libatspi2.0-0 libcups2 libdbus-1-3 \
  libdrm2 libgbm1 libgtk-3-0 libnspr4 libnss3 \
  libpango-1.0-0 libpangocairo-1.0-0 libwayland-client0 \
  libwayland-server0 libxcomposite1 libxdamage1 \
  libxkbcommon0 libxrandr2 libxss1 xdg-utils xvfb

En Ubuntu 24.04 algunos nombres de paquete han cambiado. Si apt informa de un paquete desconocido, busca la variante renombrada con apt-cache search o parte de esta lista reducida:

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

Paso 2: iniciar Xvfb

Inicia Xvfb en la pantalla :10 antes de cualquier proceso de BotBrowser y conecta a ella todos los workers del navegador.

Para una prueba inmediata:

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

Para producción, crea un servicio 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

Habilita e inicia el servicio:

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

Paso 3: instalar BotBrowser

Descarga el paquete de Linux que coincida con tu arquitectura desde la página de versiones de BotBrowser. La compatibilidad con arquitecturas depende de cada versión, así que confírmala allí. La guía de instalación indica que los binarios de Ubuntu requieren una suscripción ENT Plan Tier 1 o superior.

# Instala el paquete descargado
sudo dpkg -i botbrowser_<version>_amd64.deb

# Resuelve las dependencias que dpkg indique como ausentes
sudo apt-get install -f

# Verifica la instalación
chromium-browser --version

Paso 4: descargar perfiles

Usa el paquete de perfil que coincida con la versión instalada del navegador. Los perfiles de BotBrowser 150 y posteriores están disponibles mediante suscripción o soporte. Haz que solo la cuenta de servicio pueda leer el paquete; en los ejemplos se llama botbrowser.

sudo mkdir -p /var/lib/botbrowser
sudo install -o botbrowser -g botbrowser -m 600 \
  /path/to/<matching-profile>.enc /var/lib/botbrowser/profile.enc

Paso 5: prueba de lanzamiento

Usa la tarea de prueba con Playwright del paso 6 para comprobar la ruta de lanzamiento completa. Ejecútala con la cuenta de servicio, el paquete de perfil, el directorio de trabajo y la ruta gráfica previstos para producción, y con DISPLAY=:10.0 definido. Una prueba correcta abre la página aprobada, completa su pequeña acción y se cierra con normalidad.

Paso 6: integración con Playwright

npm install playwright-core

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

(async () => {
  const browser = await chromium.launch({
    executablePath: '/usr/bin/chromium-browser',
    args: ['--bot-profile=/var/lib/botbrowser/profile.enc', '--proxy-server=socks5://user:[email protected]: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();
})();

Ejecútala con la variable de pantalla definida:

DISPLAY=:10.0 node script.js

Paso 7: servicio systemd para automatización

Para workers de automatización persistentes:

# /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=on-failure
RestartSec=10
User=botbrowser
Group=botbrowser

[Install]
WantedBy=multi-user.target

Gestionar una carga por servicio

Asocia cada unidad a systemctl status botbrowser-worker.service y a un WorkingDirectory propio; así el estado del servicio identifica la carga concreta que debe reiniciarse.

Haz que cada unidad de servicio se encargue de una carga definida y de un directorio de datos. La aplicación debe controlar el inicio y el cierre del navegador para que el supervisor vea un estado de proceso claro. Esta disposición también facilita asociar registros, límites de recursos y política de reinicio con la carga que los generó.

Crea unidades de servicio separadas cuando las aplicaciones tengan calendarios de versiones, requisitos gráficos o límites de seguridad distintos. No pongas un bucle de shell alrededor de varios lanzamientos de perfil. Un bucle oculta qué tarea falló y puede dejar procesos hijos activos cuando el proceso padre termina.

Usa el gestor de servicios para el comportamiento de reinicio. Define un retraso entre intentos y un límite de arranques para que un perfil no válido o una imagen dañada no cree un ciclo de reinicio continuo. Una carga fallida debe seguir visible para la monitorización hasta que se corrija la configuración de fondo.

Verificación, salud y recuperación

Tras completar la configuración, verifica la pantalla, las dependencias del navegador y un lanzamiento headless:

# Comprueba que Xvfb está en ejecución
systemctl status xvfb

# Comprueba que la pantalla es accesible
DISPLAY=:10.0 xdpyinfo | head -5

# Comprueba que se cumplen las dependencias del navegador
ldd /usr/bin/chromium-browser | grep "not found"

# Lanza y verifica la navegación en modo headless con la pantalla definida
DISPLAY=:10.0 node -e "
const { chromium } = require('playwright-core');
(async () => {
  const b = await chromium.launch({
    executablePath: '/usr/bin/chromium-browser',
    args: ['--bot-profile=/var/lib/botbrowser/profile.enc'],
    headless: true,
  });
  const p = await (await b.newContext()).newPage();
  await p.goto('https://example.com');
  console.log('Navigation completed:', await p.title());
  await b.close();
})();
"

El navegador debe iniciarse sin abrir una ventana de orientación visible, completar la navegación y terminar con normalidad. Conserva la salida del terminal y el código de salida del proceso con los registros del despliegue.

Orden de triaje de fallos

Cuando un host Ubuntu headless se ejecuta pero devuelve un renderizado incorrecto, sigue un orden fijo de comprobaciones para que cada resultado descarte una sola capa: servicio de pantalla, pantalla, renderizador gráfico, paquete de perfil y, por último, la tarea de la aplicación. Saltar directo a la aplicación oculta la deriva del host detrás de un informe de fallo no relacionado.

1. Ejecuta systemctl status xvfb. Un aprobado muestra active (running), un tiempo de actividad estable y un contador de reinicios que no sube.
2. Ejecuta DISPLAY=:10.0 xdpyinfo | head -5. Un aprobado informa las dimensiones y la profundidad aprobadas, por ejemplo dimensions: 1920x1080 pixels y depth of root window: 24 planes.
3. Ejecuta DISPLAY=:10.0 glxinfo -B. Un aprobado nombra el renderizador de software aprobado en OpenGL renderer string, por ejemplo llvmpipe (LLVM ...).
4. Lee la cadena del renderizador dentro de la sesión del navegador y compárala con el paso 3. Una diferencia significa que los flags de lanzamiento eligen otra ruta que la predeterminada del host.
5. Compara sha256sum /var/lib/botbrowser/profile.enc con el valor aprobado. Un valor distinto significa que se carga el paquete equivocado, no un fallo de renderizado.
6. Repite la tarea de humo del Paso 6 con la misma pantalla, perfil y flags, y compara la captura con la línea base aprobada.

Detente en el primer paso que falle y repara esa capa antes de repetir todo el orden. Una pantalla que falla el paso 2 explica todos los síntomas visuales posteriores, y ninguna combinación de flags arregla una unidad detenida.

Síntoma	Comprobación	Decisión
El lanzamiento termina con "cannot open display"	systemctl status xvfb y systemctl is-active xvfb	Repara o reinicia la unidad de pantalla antes de tocar los flags del navegador
La página carga pero faltan glifos	Recuento de fc-list contra la lista de paquetes de la imagen aprobada	Trátalo como deriva de paquetes de fuentes y reconstruye la imagen
El área de canvas, WebGL o medios queda en blanco	Cadena del renderizador en glxinfo -B	Alinea los flags con el backend aprobado y repite la tarea de humo
Las capturas salen recortadas o escaladas	Dimensiones de xdpyinfo frente al tamaño de pantalla del perfil	Sube la pantalla de Xvfb o corrige la selección del perfil
El mismo perfil se renderiza distinto en dos hosts	Cadena del renderizador y salida de sha256sum de ambos hosts	Separa el grupo por clase de host hasta explicar la diferencia

Mismo perfil, dos hosts, renderizado distinto

El fallo más difícil es silencioso. Dos hosts devuelven una tarea correcta, pero el mismo perfil aprobado renderiza texto, canvas o vídeo de forma distinta. La comprobación de procesos da ambos hosts por sanos, así que la diferencia solo aparece en una comparación de píxeles o en un informe de operador. Aísla la causa en tres pasadas, cambiando un factor a la vez y manteniendo fijos los otros dos.

Comprueba la pantalla primero. Compara DISPLAY=:10.0 xdpyinfo en ambos hosts: dimensiones, profundidad y número de pantallas deben coincidir con la configuración aprobada. Un host con pantalla de 16 bits o un framebuffer menor escala o recorta el contenido antes de que el navegador dibuje nada.

Comprueba el backend GPU después. Compara glxinfo -B en ambos hosts y lee OpenGL renderer string y OpenGL version string. Dos hosts que informan llvmpipe, o uno llvmpipe y otro SwiftShader, son clases de despliegue distintas aunque ambos pasen la tarea de humo. Registra el backend en el registro de versión para que la comparación sea repetible.

Comprueba el perfil al final. Compara sha256sum /var/lib/botbrowser/profile.enc y la versión del perfil en ambos hosts. Un host que carga un paquete más antiguo, o uno compilado para otra versión del navegador, produce fuentes, valores de pantalla o comportamiento de medios distintos y aún devuelve HTTP 200.

Cuando dos de los tres inputs coinciden, la diferencia restante apunta al tercero, y el grupo debe separarse por clase de host hasta que un responsable lo explique. No promedies los dos resultados ni promociones el host más rápido como referencia.

Estado de servicio y controles de salud

La comprobación mínima registra systemctl is-active, exitCode=0 y el tiempo de navegación en milisegundos antes de aceptar nuevas tareas.

Define la disponibilidad a partir de la carga de trabajo, no solo de la existencia de un proceso del navegador. Una comprobación de inicio útil confirma que el servicio aceptó su configuración, creó una sesión de navegador, abrió una página aprobada y completó una pequeña acción de la aplicación. La comprobación debe detenerse rápido cuando falle cualquiera de esos pasos.

Mantén el control de salud separado del tráfico de clientes. Usa una cuenta de prueba dedicada o una página pública sin datos personales. El resultado debe indicar si la aplicación puede iniciarse, navegar y cerrarse con normalidad.

Distingue la salud de inicio de la salud continua. La salud de inicio protege las decisiones de despliegue y reinicio. La salud continua debe cubrir el avance de la cola, las tareas completadas recientemente, el estado de salida de los procesos, el espacio libre en disco, la presión de memoria y el estado de cualquier servicio de pantalla necesario. Un worker puede seguir activo aunque su aplicación haya dejado de avanzar, por lo que el tiempo de actividad del proceso por sí solo no basta.

Fija un plazo razonable para cada comprobación según la carga normal. Trata los tiempos de espera repetidos como un fallo del servicio y conserva la salida de la aplicación que explica el último paso completado. Evita un intervalo agresivo que compita con el trabajo de producción o inicie sesiones completas del navegador una y otra vez.

Cuando una comprobación falle, retira al worker de las nuevas asignaciones antes de reiniciarlo. Deja que la tarea activa termine solo si la aplicación puede hacerlo con seguridad. De lo contrario, registra la tarea interrumpida, detén el servicio y devuelve el directorio de datos a un estado conocido antes de que el supervisor lo intente de nuevo.

Registros y recuperación ante fallos

Envía la salida de la aplicación y la salida de terminal del navegador al destino de registro habitual de la plataforma. Incluye la revisión del servicio, la versión de BotBrowser, la versión del paquete de perfil, la imagen del servidor y el identificador de la tarea. Excluye el contenido de las páginas, las credenciales, los secretos de ruta y los datos de clientes. El objetivo es explicar un evento del servicio sin convertir el registro en una copia de la sesión de navegación.

Rota los registros y los artefactos de fallo antes de que llenen el disco del worker. Conserva historial suficiente para comparar la versión candidata con la última aprobada y aplica después la política de retención habitual de la organización. Un periodo de retención fijo resulta menos útil que una política ligada a la respuesta a incidentes y a los requisitos de privacidad.

Clasifica los fallos según la acción que debe tomar un operador. Los fallos de configuración requieren corregir el servicio o el paquete de perfil. Los fallos de dependencias requieren reparar la imagen del servidor. Los fallos de recursos requieren revisar la carga o la capacidad. Los fallos de aplicación corresponden a su responsable. Este modelo sencillo de responsabilidades evita que los reinicios repetidos oculten un problema persistente del despliegue.

Prueba la recuperación en preproducción. Detén el servicio durante una tarea de prueba aprobada, reinicia el host y deja temporalmente sin disponibilidad una dependencia necesaria. Confirma que la monitorización señala el servicio correcto, que el supervisor respeta su límite de reinicios y que la siguiente tarea parte de un estado aprobado. La evidencia de recuperación debe formar parte de la revisión de la imagen.

Control de cambios y aprobación de la versión

Conserva imageDigest, browserVersion y profileSha256 en la ficha de candidato; la combinación permite distinguir una actualización de imagen de un cambio de perfil.

Trata la imagen del sistema operativo, la versión del navegador, el paquete de perfil, la unidad de servicio y la aplicación como una única combinación de despliegue registrada. Un cambio en cualquier capa puede afectar al inicio, al renderizado, a los medios o al uso de recursos. Registra cada combinación candidata antes de probarla para que un revisor pueda reproducirla.

Aplica los cambios de imagen por la misma vía de preproducción que los cambios de la aplicación. Las actualizaciones de paquetes, los paquetes de fuentes, las bibliotecas gráficas, los cambios del entorno de contenedores y las actualizaciones de la política de seguridad merecen una tarea representativa del navegador. Aprobar la imagen base por separado de la carga del navegador deja una brecha importante.

Promociona los cambios en grupos pequeños. Cuando varias capas deban cambiar a la vez, conserva disponible la combinación anterior y documenta el orden de reversión. La reversión debe restaurar una combinación aprobada completa, no mezclar un navegador antiguo con un perfil o un archivo de servicio sin revisar.

Después de la promoción, observa la finalización de tareas, la frecuencia de reinicios, el crecimiento del disco y la presión sobre los recursos durante la ventana de versión habitual. Compara estos resultados con la ejecución aprobada en preproducción. Un candidato que arranca bien pero se degrada con el trabajo normal debe retirarse del grupo antes de que afecte a más tareas.

Inicio headless y orientación del perfil

BotBrowser 150 no abre ventanas visibles de orientación del perfil en los lanzamientos headless. Los paquetes de perfil ausentes, caducados, no válidos o con versión incompatible se notifican en la salida del terminal, y el proceso sigue la ruta normal de fallo de arranque. Los lanzamientos con interfaz conservan la orientación para el usuario.

Esto importa en flotas de Playwright y workers de CI porque un problema de arranque no debe crear una dependencia oculta del escritorio ni una ventana inesperada. Captura el stderr del navegador junto con los registros del trabajo, trata la orientación del perfil como un lanzamiento fallido y sustituye el paquete de perfil antes de reintentar.

Los registros del contenedor aún pueden mencionar servicios de escritorio o gráficos no disponibles. Juzga la disponibilidad por la creación correcta de la sesión, la finalización de la tarea de prueba aprobada y el backend gráfico seleccionado. Las bibliotecas del host y el paquete de perfil siguen debiendo coincidir con la guía de despliegue.

Reglas operativas

Define DISPLAY=:10.0 en cada servicio de BotBrowser. Mantenlo en cada archivo de servicio en lugar de depender de un shell de inicio de sesión, para que los reinicios del servicio y del host arranquen con el mismo entorno.

Valida la configuración de pantalla de Xvfb. Una pantalla de 24 bits es un punto de partida práctico, pero la aprobación debe basarse en comprobaciones representativas de renderizado y capturas. Aumenta la resolución de Xvfb cuando las dimensiones de pantalla del perfil la superen.

Monitoriza el uso de disco. El navegador escribe volcados de fallos y datos de caché en el directorio definido con --user-data-dir. Configura la rotación de registros o una limpieza periódica para evitar que se agote el disco.

Mantén las dependencias actualizadas. Ejecuta apt-get upgrade periódicamente. Las diferencias de versión entre bibliotecas pueden causar problemas de renderizado sutiles.

Define límites de recursos. Usa las opciones de systemd MemoryMax y CPUQuota para evitar que un servicio fuera de control consuma todos los recursos del servidor.

Aprobación de la versión

Aprueba la imagen del servidor y la versión de BotBrowser como una única combinación de despliegue. Registra la versión de Ubuntu, la versión de BotBrowser, el paquete de perfil, la ruta gráfica, la configuración de pantalla de Xvfb, la revisión del archivo de servicio y la revisión de la aplicación. Un resultado correcto en otra imagen es un contexto útil, pero no sustituye la validación en la imagen que llegará a producción.

Empieza con un arranque en frío en un worker limpio. Confirma que el servicio alcanza el estado listo, abre una página representativa, completa una tarea normal y se cierra con limpieza. Repite la misma tarea tras reiniciar el servicio y tras reiniciar el host. Estas ejecuciones detectan variables de entorno ausentes, permisos, tiempos de montaje y problemas de orden entre servicios que una shell interactiva puede ocultar.

Revisa a continuación el resultado visible para el usuario. Incluye una página normal de la aplicación, una página con mucho texto, un flujo de capturas o documentos y los medios cuando el producto los use. Busca caracteres ausentes, controles recortados, regiones en blanco, reproducciones fallidas y cambios inesperados en el tamaño de página. La regla de aceptación debe venir del responsable de la aplicación y no de una tolerancia universal fija.

La aprobación de capacidad necesita una mezcla representativa de tareas. Aumenta la concurrencia de forma gradual mientras vigilas la memoria, la CPU, la memoria compartida, los descriptores de archivo, el crecimiento del disco y el tiempo de finalización de las tareas. Deja margen suficiente para el sistema operativo, el registro y los picos breves de carga. Anota el rango aprobado para esa imagen exacta y revísalo cuando cambien la mezcla de páginas o la versión del navegador.

La gestión de fallos forma parte de la aprobación. Detén un worker durante una tarea, aporta un perfil caducado o incompatible en una ejecución controlada de preproducción y verifica que el supervisor registre el fallo y devuelva al worker a un estado conocido. Los reintentos no deben reutilizar un directorio de datos de usuario dañado. Los registros deben identificar la versión y el worker sin contener secretos de clientes.

Promociona la imagen solo después de que la tarea representativa pase en cada clase de host que la reciba. Si se usan un grupo con GPU y otro con renderizado por software, trátalos como clases de despliegue distintas. Mantén disponible la imagen aprobada anterior para revertir hasta que el candidato complete el periodo de observación habitual de la organización.

Preguntas sobre hosts Ubuntu headless

¿Funciona BotBrowser en Ubuntu 24.04?

La documentación indica Ubuntu 20.04 o posterior. En 24.04 algunos nombres de paquete cambiaron, por ejemplo libasound2 pasó a ser libasound2t64, así que usa el comando de instalación alternativo del paso 1 y valida el resultado en tu host.

¿Puedo usar una resolución de Xvfb más alta?

Sí. Puedes iniciar Xvfb con -screen 0 2560x1440x24 o con el tamaño que necesite tu carga. Auméntala cuando las dimensiones de pantalla del perfil superen el valor por defecto y confirma el resultado con capturas representativas.

¿Necesito una GPU en el servidor?

Depende de la carga y del backend gráfico de Linux elegido. La automatización básica puede usar una ruta por software validada, mientras que las cargas con medios, WebGL o muchas capturas pueden comportarse de forma distinta en otras rutas gráficas. Prueba la configuración prevista de la versión en el host de destino.

¿Sigo necesitando Xvfb en modo headless?

En un servidor sin escritorio, el proceso necesita una pantalla virtual para crear su contexto gráfico. Define la variable de entorno en el servicio, verifica con xdpyinfo y conserva la salida del lanzamiento junto con las capturas de prueba.

¿Por qué no hay ventana cuando falla un lanzamiento headless?

El modo headless notifica la orientación de arranque en la salida del terminal en lugar de abrir una ventana de escritorio. Conserva esa salida con los registros del worker y corrige el problema del perfil o del host antes de reintentar.

¿Cuántas instancias puedo ejecutar por servidor?

Depende del host y de la carga de páginas. Mide páginas representativas con el perfil, el backend gráfico, los medios, las capturas y la actividad de workers previstos. Deja margen para el sistema operativo, vigila la presión de memoria y de swap, y reduce la concurrencia antes de que el host se vuelva inestable.

¿Cómo compruebo las bibliotecas que faltan?

Ejecuta ldd /usr/bin/chromium-browser | grep "not found". Cualquier biblioteca marcada como "not found" debe instalarse. Usa apt-file search libname.so para encontrar el paquete que proporciona una biblioteca concreta.

¿Puedo ejecutar BotBrowser en servidores Ubuntu con ARM?

Las notas de cada lanzamiento enumeran las arquitecturas compatibles. Consulta la página de versiones de GitHub antes de planificar un grupo ARM; no reutilices una imagen x86_64 en un grupo arm64 sin una verificación separada.

¿Cómo actualizo BotBrowser?

Descarga la última versión y prepárala con el paquete de perfil correspondiente. Revisa la configuración del servicio, las dependencias, la ruta gráfica y la carga representativa antes de promocionarla, porque los cambios de versión pueden afectar a las suposiciones del despliegue. Mantén disponible la combinación aprobada anterior hasta que la actualización supere el periodo de observación habitual.

Decisión de despliegue

Configurar BotBrowser en un servidor Ubuntu headless requiere las dependencias del sistema correctas, un backend gráfico probado y una configuración de servicio fiable. Ejecuta Xvfb en la pantalla :10.0 y define DISPLAY en cada servicio de BotBrowser. Mide páginas representativas antes de fijar límites de concurrencia, conserva margen de capacidad y mantén los datos privados fuera de los registros. Descarga BotBrowser para empezar.

BotBrowser soporta flotas de servidores headless de dos maneras documentadas. Lee propiedades de huella como el tamaño de pantalla, las fuentes y la información de GPU del paquete de perfil seleccionado en lugar del hardware del servidor y, en los lanzamientos headless, notifica en la salida del terminal los estados de perfil ausente, no válido, caducado o con versión incompatible, de modo que un worker falla de forma visible y sin ventana oculta. Así las propiedades se mantienen coherentes entre hosts aprobados y el operador recibe un mensaje legible en el registro del trabajo. BotBrowser no puede instalar las bibliotecas, las fuentes ni el backend gráfico del host, no puede garantizar un renderizado, unos medios o una capacidad idénticos entre clases de host y no sustituye la validación de cada imagen y carga antes de producción.

Para despliegues en contenedores, consulta la guía de despliegue con Docker. Para planificar la capacidad, consulta la optimización de rendimiento de BotBrowser. Para combinaciones de opciones de la CLI, consulta las recetas de CLI.

Conclusión práctica

Trata el host, la versión del navegador, el perfil, la ruta gráfica y la carga como una única combinación probada. BotBrowser puede hacer repetibles las sesiones autorizadas, pero las dependencias, permisos, resultados de la aplicación y controles de privacidad siguen siendo responsabilidad del operador.

Para medir cómo difieren las sesiones con interfaz y headless antes de apoyarte en una, consulta el método de comparación de señales.

Fuentes públicas

• Documentación de BotBrowser: configuración de servidores headless
• Documentación de BotBrowser: selección del backend gráfico de Linux
• Versiones de BotBrowser
• Manual de systemd.service