Overview

This guide provides step-by-step instructions to set up your own Steel Browser instance using Docker. The setup consists of multiple deployment options – from the traditional docker-compose setup to the new, simplified single Docker image deployment.

Prerequisites

• Docker (20.10.0 or later)
• At least 4GB of RAM
• 10GB of free disk space

Quick Start Using Docker Compose

1. 1Create a new directory for your Steel Browser instance:

mkdir steel-browser && cd steel-browser

1. 1Create the following file:

docker-compose.yaml

1
services:
2
  api:
3
    image: ghcr.io/steel-dev/steel-browser-api:latest
4
    ports:
5
      - "3000:3000"
6
      - "9223:9223"
7
    volumes:
8
      - ./.cache:/app/.cache
9
    networks:
10
      - steel-network
11

12
  ui:
13
    image: ghcr.io/steel-dev/steel-browser-ui:latest
14
    ports:
15
      - "5173:80"
16
    depends_on:
17
      - api
18
    networks:
19
      - steel-network
20

21
networks:
22
  steel-network:
23
    name: steel-network
24
    driver: bridge

1. 1Launch the containers:

docker compose up -d

1. 1Access Steel Browser by opening http://localhost:5173 in your web browser.

Alternative Deployment: Single Docker Image

Steel Browser can now be deployed using a single Docker image—no more complex docker-compose setup!

Single Docker Image Deployment

Run the following command to launch Steel Browser:

docker run --rm -it -p 3000:3000 -p 9223:9223 ghcr.io/steel-dev/steel-browser:latest

This command will:

• Pull the latest Docker image from GitHub Container Registry.
• Expose the API on port 3000 and Chrome debugging on port 9223.
• Run the container interactively and remove it when stopped.

Access Steel Browser via your browser at http://localhost:3000 and the UI at http://localhost:3000/ui.

Building the Singular Docker Image Locally

If you wish to build the Docker image from source rather than relying on the pre-built image, follow these steps:

1. 1Clone the repository:

git clone https://github.com/steel-dev/steel-browser.git
cd steel-browser

1. 1Build the Docker image:

docker build -t steel-browser:local .

1. 1Run the newly built image:

docker run --rm -it -p 3000:3000 -p 9223:9223 steel-browser:local

This method gives you the flexibility to modify the image locally. Compared to the docker-compose setup where the API and UI are managed in separate containers, here everything runs within one container, simplifying deployment for testing and development.

Advanced Setup

Building From Source with Docker Compose

If you prefer to build the containers yourself with docker-compose:

1. 1Clone the repository:

git clone https://github.com/steel-dev/steel-browser.git
cd steel-browser

1. 1

   Create a .env file (optional).

2. 2

   Build and start using the development compose file:

docker compose -f docker-compose.dev.yml up -d --build

The “-d” flag runs the containers in the background.

Configuration Options

• API Port: Default is 3000 (internally also 3000). If changed in the compose file, update the API binding accordingly.
• UI Port: Default is 5173 (or 80 inside container). Adjust if needed.
• Chrome Debugging Port: Default is 9223. Required for browser communication.

Volume Persistence

The .cache directory stores Chrome data and extensions. Mount it as a volume for persistence:

1
volumes:
2
  - ./.cache:/app/.cache

Architecture

Steel Browser consists of two main components when using docker-compose:

1. 1API Container: Runs Chrome in headless mode and provides CDP (Chrome DevTools Protocol) services.
2. 2UI Container: An Nginx-based frontend for interacting with the browser.

When using the single Docker image deployment, both the API and UI are integrated into one container.

Customizing the Build

Using a Different Chrome Version

The API container uses Chrome 128.0.6613.119 by default. To use a different version:

1. 1Create a custom Dockerfile based on the API one.
2. 2Modify the Chrome installation section:

1
ARG CHROME_VERSION="128.0.6613.119"
2
RUN apt-get update && \
3
    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
4
    wget \
5
    ca-certificates \
6
    curl \
7
    unzip \
8
    && CHROME_DEB="google-chrome-stable_${CHROME_VERSION}-1_amd64.deb" \
9
    && wget -q "https://mirror.cs.uchicago.edu/google-chrome/pool/main/g/google-chrome-stable/${CHROME_DEB}"
10
    # ...rest of the installation...

Changing Node Version

Both containers use Node 22.13.0 by default. To use a different version, modify the build arguments:

1
services:
2
  api:
3
    build:
4
      context: .
5
      dockerfile: ./api/Dockerfile
6
      args:
7
        NODE_VERSION: 18.19.0

Troubleshooting

Chrome Won't Start

Ensure your host has enough resources and check the API container logs:

1
docker logs steel-browser_api_1

Common issues include:

• Running on ARM architecture (There are official images for ARM, or build the image yourself)
• Insufficient memory
• Missing shared libraries
• Permission issues with the .cache directory

Connectivity Issues

If the UI can't connect to the API:

1. 1Verify both containers are running.
2. 2Check if the API is accessible:

1
curl http://localhost:3000/api/health

1. 1Ensure the containers can communicate over the network:

1
docker exec steel-browser_ui_1 curl http://api:3000/api/health

Production Deployment

For production environments:

1. 1Use specific image versions rather than latest.
2. 2Set up a proper reverse proxy with HTTPS.
3. 3Configure appropriate resource limits.

Example production compose file:

1
services:
2
  api:
3
    image: ghcr.io/steel-dev/steel-browser-api:sha256:...
4
    restart: always
5
    ports:
6
      - "3000:3000"
7
    deploy:
8
      resources:
9
        limits:
10
          memory: 2G
11
    volumes:
12
      - ./data/.cache:/app/.cache
13
    networks:
14
      - steel-network
15

16
  ui:
17
    image: ghcr.io/steel-dev/steel-browser-ui:sha256:...
18
    restart: always
19
    ports:
20
      - "5173:80"
21
    networks:
22
      - steel-network
23

24
networks:
25
  steel-network:
26
    name: steel-network
27
    driver: bridge

Security Considerations

• Avoid exposing the Chrome debugging port (9223) to the public internet.
• Consider not exposing the API if the UI and API are running within the same secured network.
• Set up proper authentication if deploying publicly.
• Keep containers updated with the latest versions.

Updating

To update to the latest version:

1
docker compose pull
2
docker compose up -d

For custom builds:

1
git pull
2
docker compose -f docker-compose.dev.yml up -d --build