Docker Deployment
Relevant source files
The following files were used as context for generating this wiki page:
The Docker deployment system for the Web UI project provides a containerized environment that encapsulates the Gradio-based web interface, a persistent or ephemeral browser instance, and the necessary infrastructure for remote visualization. It is designed to support multiple architectures (AMD64 and ARM64) and simplifies the complex setup of LLM agents by bundling dependencies like Playwright and Chromium with a graphical display server.
Sources: README.md:92-111, docker-compose.yml:1-8
Container Architecture and Orchestration
The deployment utilizes a single service architecture managed by Docker Compose. Within the container, multiple processes are orchestrated by supervisord to ensure the system handles display rendering, VNC access, and the application logic simultaneously.
Service Stack
The browser-use-webui service runs on linux/amd64 by default but supports ARM64 (Apple Silicon) automatically. It manages several networked components:
- Web UI: The primary interface served via Gradio on port 7788.
- noVNC: A web-based VNC client accessible on port 6080 for real-time browser monitoring.
- VNC Server: Direct RFB access on port 5901.
- Chrome Debugging: Remote debugging capabilities via port 9222.
Sources: docker-compose.yml:3-16, README.md:118-124, supervisord.conf:1-5
Process Management Flow
The system uses a prioritized startup sequence defined in supervisord.conf to ensure dependencies are met before the Web UI launches.
This diagram represents the execution priority and dependency chain managed by Supervisor inside the container.
Sources: supervisord.conf:10-95
Configuration and Environment Variables
Configuration is handled primarily through a .env file mapped to container environment variables. This includes LLM API credentials, browser behavioral settings, and display resolutions.
LLM Connectivity
The container supports multiple providers. If keys are not provided in the environment, they must be entered manually through the Web UI.
| Variable | Description | Default/Example |
|---|---|---|
OPENAI_API_KEY | API Key for OpenAI models | - |
ANTHROPIC_API_KEY | API Key for Anthropic models | - |
GOOGLE_API_KEY | API Key for Google Gemini models | - |
DEEPSEEK_API_KEY | API Key for DeepSeek models | - |
OPENAI_ENDPOINT | Custom endpoint for OpenAI-compatible APIs | https://api.openai.com/v1 |
Sources: docker-compose.yml:18-26, README.md:113-116, src/utils/default_config_settings.py:14-18
Browser Persistence Modes
The system supports two distinct operational modes for the browser:
- Default Mode (
CHROME_PERSISTENT_SESSION=false): The browser context is created and destroyed for each AI task, ensuring a clean state and lower resource consumption. - Persistent Mode (
CHROME_PERSISTENT_SESSION=true): A Chromium instance is launched by Supervisor at startup and maintained throughout the container's lifecycle. This allows the AI to maintain history, logins, and state across different tasks.
Sources: README.md:126-140, docker-compose.yml:29-31, supervisord.conf:72-84
System Infrastructure
Display and Visualization
To run a browser in a headless Docker environment while allowing user monitoring, the system implements a virtual framebuffer and VNC stack.
- Xvfb: Creates a virtual display
:99in memory. The resolution is configurable viaRESOLUTION(default1920x1080x24). - x11vnc: Scrapes the Xvfb display and serves it via the RFB protocol. It uses a password defined by
VNC_PASSWORD(defaulting tovncpassword). - noVNC: Provides a WebSocket-to-TCP bridge, allowing the VNC stream to be viewed in a standard web browser at
http://localhost:6080/vnc.html.
Sources: supervisord.conf:10-63, docker-compose.yml:32-37
Persistence and Volumes
The container uses specific paths for data persistence to ensure browser profiles and session data survive container restarts.
- Chrome Data: Stored at
/app/data/chrome_datawithin the container. - Shared Memory: The container is configured with
shm_size: '2gb'to prevent browser crashes during heavy page rendering. - X11 Unix Socket: Optionally mounts
/tmp/.X11-unixfor host-container display integration.
Sources: docker-compose.yml:28, 39-42, supervisord.conf:74
Execution Sequence
The following sequence diagram illustrates how a user interaction initiates the browser via the Docker-deployed stack.
The interaction flow between the user, the Gradio interface, and the underlying browser infrastructure.
Sources: webui.py:381-421, supervisord.conf:86-95
Summary
The Docker deployment of the Web UI project provides a robust, multi-process environment that abstracts the complexities of browser automation. By leveraging supervisord to manage Xvfb, VNC, and Chromium alongside the Web UI, it offers a "plug-and-play" solution for running AI agents with full visual feedback and optional session persistence. The configuration via environment variables and Docker Compose ensures compatibility across different hardware architectures and LLM providers.
Sources: README.md:92-111, docker-compose.yml:1-55