Volver al Blog
Despliegue

Guía de despliegue de BotBrowser con Docker

Buenas prácticas para desplegar BotBrowser en contenedores Docker: Dockerfile, Docker Compose, volúmenes y endurecimiento para producción.

Introducción

Docker ofrece la repetibilidad, aislamiento y escalabilidad necesarias para desplegar BotBrowser en producción. Cada contenedor arranca desde un estado conocido, se ejecuta de forma aislada y puede replicarse en cualquier infraestructura que soporte Docker, evitando el clásico "en mi máquina funciona".

Esta guía cubre el flujo completo de despliegue con Docker: construir imágenes, gestionar archivos de configuración y scripts mediante volúmenes, configurar la memoria compartida, usar Docker Compose para escalar y aplicar endurecimientos para producción. Los patrones son aplicables tanto a un contenedor local como a clusters en la nube.

Por qué desplegar con Docker

BotBrowser depende de bibliotecas del sistema, servidores de visualización virtual y configuraciones específicas. En un host sin contenedores, cada servidor requiere instalar dependencias, configurar Xvfb, establecer variables de entorno y verificar la instalación. Docker encapsula todo esto en una imagen, asegurando consistencia entre entornos.

Docker también aísla procesos: cada contenedor ejecuta una instancia independiente de BotBrowser con su propio sistema de archivos, espacio de red y límites de recursos. Una fuga de memoria en un contenedor no afecta a los demás, y Docker puede reiniciar automáticamente procesos fallidos mediante políticas de reinicio.

Para equipos que necesiten múltiples instancias con diferentes perfiles y proxies, Docker Compose o plataformas de orquestación permiten definir, escalar y gestionar el conjunto desde un único archivo de configuración.

Antecedentes técnicos

Chrome y memoria compartida

Chrome hace un uso intensivo de /dev/shm (memoria compartida) para IPC entre procesos del navegador, GPU y renderizado. El tamaño por defecto en Docker es 64 MB, lo cual suele ser insuficiente. Chrome puede fallar sin al menos 1–2 GB de memoria compartida.

La solución es añadir --shm-size=2g al docker run o shm_size: '2g' en Docker Compose.

Servidor de visualización en contenedores

Al igual que en hosts físicos, BotBrowser necesita Xvfb dentro del contenedor. Iniciar Xvfb antes de lanzar Chrome y configurar DISPLAY es obligatorio.

Directorio de datos de usuario

Cada instancia de BotBrowser requiere su propio --user-data-dir. En contenedores, este directorio es efímero a menos que se monte un volumen persistente. Monte un volumen si necesita persistencia entre reinicios.

Tamaño de la imagen

Una imagen Docker con todas las dependencias para BotBrowser suele ocupar 500–800 MB. Use builds multi-stage o depuración de paquetes para reducir tamaño, teniendo en cuenta que librerías faltantes pueden provocar errores en tiempo de ejecución.

Docker Container Xvfb :10 Virtual Display BotBrowser Chrome + Profile Node.js Automation Script /dev/shm 2 GB Shared Mem Volume: /opt/profiles (host mounted) Volume: /data/sessions (persistent)

Métodos comunes

Contenedor monolítico

Ejecutar todo (Xvfb, BotBrowser, scripts y supervisión) en un único contenedor es sencillo pero limita la escalabilidad: no se pueden escalar los scripts independientemente y un fallo en cualquiera de los componentes detiene todo el contenedor.

Un contenedor por navegador

Proporciona mejor aislamiento: cada instancia tiene su propio perfil, proxy y directorio de datos. El coste por instancia aumenta, pero la escalabilidad y depuración mejoran.

Patrón sidecar

Un contenedor sidecar que ejecute Xvfb y sirva a múltiples navegadores reduce consumo pero introduce complejidad y un posible punto único de fallo.

Construir sobre la imagen oficial de Chromium

La imagen oficial puede ahorrar trabajo inicial, pero puede faltar alguna dependencia que BotBrowser requiera. Construir sobre Ubuntu permite controlar las dependencias con más precisión.

Enfoque recomendado

Usa Ubuntu 22.04 como base, instala dependencias del sistema, copia el binario de BotBrowser y perfiles y arranca Xvfb antes del script de automatización. Esta plantilla ha sido probada y ofrece resultados consistentes entre proveedores cloud.

Configuración y uso

Dockerfile básico

FROM ubuntu:22.04

# Install system dependencies
RUN apt-get update && 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 curl \
    && rm -rf /var/lib/apt/lists/*

# Install Node.js
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y nodejs \
    && rm -rf /var/lib/apt/lists/*

# Set display environment
ENV DISPLAY=:10.0

# Copy BotBrowser binary
COPY botbrowser/ /opt/botbrowser/
RUN chmod +x /opt/botbrowser/chrome

# Copy profiles
COPY profiles/ /opt/profiles/

# Copy automation scripts
WORKDIR /opt/app
COPY package.json package-lock.json ./
RUN npm ci --production
COPY scripts/ ./scripts/

# Health check
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD pgrep -x Xvfb && pgrep -f "chrome" || exit 1

# Start Xvfb and run the automation script
CMD Xvfb :10 -screen 0 1920x1080x24 -ac & \
    sleep 1 && \
    node scripts/main.js

Build y run

docker build -t botbrowser-worker .
docker run --rm --shm-size=2g botbrowser-worker

Recuerda --shm-size=2g.

Script de automatización

// scripts/main.js
const { chromium } = require('playwright-core');

const PROFILE = process.env.PROFILE || '/opt/profiles/profile.enc';
const PROXY = process.env.PROXY || '';

async function main() {
  const args = [
    '--disable-setuid-sandbox',
    `--bot-profile=${PROFILE}`,
  ];

  if (PROXY) args.push(`--proxy-server=${PROXY}`);

  const browser = await chromium.launch({
    executablePath: '/opt/botbrowser/chrome',
    args: args,
    headless: true,
  });

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

process.on('SIGTERM', async () => { console.log('SIGTERM'); process.exit(0); });
process.on('SIGINT', async () => { console.log('SIGINT'); process.exit(0); });

main().catch(console.error);

Docker Compose para múltiples workers

version: '3.8'

services:
  worker-us:
    build: .
    shm_size: '2g'
    environment:
      - PROFILE=/opt/profiles/windows-chrome-131.enc
      - PROXY=socks5://user:pass@us-proxy.example.com:1080
    volumes:
      - ./profiles:/opt/profiles:ro
      - session-us:/data/session
    deploy:
      resources:
        limits:
          memory: 4g
          cpus: '2'
    restart: unless-stopped

  worker-eu:
    build: .
    shm_size: '2g'
    environment:
      - PROFILE=/opt/profiles/windows-chrome-132.enc
      - PROXY=socks5://user:pass@eu-proxy.example.com:1080
    volumes:
      - ./profiles:/opt/profiles:ro
      - session-eu:/data/session
    deploy:
      resources:
        limits:
          memory: 4g
          cpus: '2'
    restart: unless-stopped

volumes:
  session-us:
  session-eu:

docker compose up -d
docker compose logs -f

Volúmenes

docker run --rm --shm-size=2g \
  -v /host/profiles:/opt/profiles:ro \
  -v /host/sessions/worker-1:/data/session \
  -e PROFILE=/opt/profiles/profile.enc \
  -e PROXY=socks5://user:pass@proxy:1080 \
  botbrowser-worker

Variables de entorno y entrypoint

Usa un entrypoint que arranque Xvfb y luego el script principal. Maneja SIGTERM para apagado limpio.

Verificación

Construye la imagen e ingresa para depuración:

docker build -t botbrowser-worker .
docker run --rm --shm-size=2g -it botbrowser-worker bash

# Dentro del contenedor
Xvfb :10 -screen 0 1920x1080x24 &
export DISPLAY=:10.0
/opt/botbrowser/chrome --version
ldd /opt/botbrowser/chrome | grep "not found"

Buenas prácticas

  • Siempre use --shm-size=2g.
  • Use --disable-setuid-sandbox en contenedores.
  • Monte perfiles como read-only.
  • Etiquete las imágenes con versiones específicas.
  • Use --init o tini para evitar procesos huérfanos.

Preguntas frecuentes

Las preguntas frecuentes incluyen problemas con /dev/shm, compatibilidad con Alpine y cómo exponer el puerto de depuración remoto.

Resumen

Docker es la forma más consistente de desplegar BotBrowser en producción. Asegúrese de asignar suficiente /dev/shm y montar perfiles para persistencia. Consulte otras guías en este repositorio para detalles adicionales.

title: "Guia de despliegue Docker para BotBrowser" description: "Despliega BotBrowser en contenedores Docker para automatizacion reproducible, aislada y a escala." date: "2026-01-07" locale: es category: deployment tags: ["docker", "deployment", "server", "automation", "devops"] published: true

Descripcion general

Docker proporciona entornos reproducibles, aislamiento de procesos y escalado facil para despliegues de BotBrowser. Cada contenedor inicia con un estado limpio y se ejecuta independientemente.

Dockerfile

FROM ubuntu:22.04

RUN apt-get update && 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 \
    && rm -rf /var/lib/apt/lists/*

ENV DISPLAY=:10.0

COPY botbrowser/ /opt/botbrowser/
COPY profiles/ /opt/profiles/
RUN chmod +x /opt/botbrowser/chrome

COPY scripts/ /opt/scripts/

CMD Xvfb :10 -screen 0 1920x1080x24 & \
    sleep 1 && \
    node /opt/scripts/main.js

Construir y ejecutar

docker build -t botbrowser-worker .
docker run --rm --shm-size=2g botbrowser-worker

El flag --shm-size=2g es importante. Chrome usa /dev/shm para memoria compartida y la asignacion predeterminada de Docker (64MB) es insuficiente.

Script de automatizacion

// /opt/scripts/main.js
const { chromium } = require('playwright-core');

(async () => {
  const browser = await chromium.launch({
    executablePath: '/opt/botbrowser/chrome',
    args: [
      '--disable-setuid-sandbox',
      '--bot-profile=/opt/profiles/profile.enc',
    ],
    headless: true,
    defaultViewport: null,
  });

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

Escalar con Docker Compose

version: '3.8'
services:
  worker-1:
    build: .
    shm_size: '2g'
    environment:
      - PROFILE=/opt/profiles/profile-1.enc
      - PROXY=socks5://proxy1:1080
  worker-2:
    build: .
    shm_size: '2g'
    environment:
      - PROFILE=/opt/profiles/profile-2.enc
      - PROXY=socks5://proxy2:1080

Mejores practicas de produccion

Limites de recursos. docker run --memory=4g --cpus=2 --shm-size=2g botbrowser-worker

Health checks. HEALTHCHECK --interval=30s --timeout=10s --retries=3 CMD pgrep chrome || exit 1

Apagado limpio. Gestiona SIGTERM:

process.on('SIGTERM', async () => {
  await browser.close();
  process.exit(0);
});

Solucion de problemas

Crash "out of memory": Aumenta --shm-size a al menos 2g.

"Cannot open display": Asegurate de que Xvfb esta ejecutandose y DISPLAY esta establecido.

"Permission denied": Usa --disable-setuid-sandbox.

Primeros pasos

  1. Descarga BotBrowser desde GitHub
  2. Construye tu imagen Docker con el Dockerfile anterior
  3. Monta perfiles y configura proxies por contenedor
#docker#deployment#server#automation#devops