SOP 009: Self-Host with Docker

Fresh

Field	Value
SOP ID	SOP-009
Version	1.0
Status	Active
Source	Steel Docker Docs

Overview

Self-host Steel Browser using Docker. Two deployment options: single Docker image (simplest) or docker-compose (API + UI separate).

Prerequisites

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

Deployment Decision

Option A: Single Docker Image (Simplest)

bash

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

Access at http://localhost:3000 (API) and http://localhost:3000/ui (UI).

Option B: Docker Compose

Step 1: Create Project Directory

bash

mkdir steel-browser && cd steel-browser

Step 2: Create docker-compose.yaml

yaml

services:
  api:
    image: ghcr.io/steel-dev/steel-browser-api:latest
    ports:
      - "3000:3000"
      - "9223:9223"
    volumes:
      - ./.cache:/app/.cache
    networks:
      - steel-network

  ui:
    image: ghcr.io/steel-dev/steel-browser-ui:latest
    ports:
      - "5173:80"
    depends_on:
      - api
    networks:
      - steel-network

networks:
  steel-network:
    name: steel-network
    driver: bridge

Step 3: Launch

bash

docker compose up -d

Step 4: Verify

bash

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

Access UI at http://localhost:5173.

Build from Source

bash

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

# Single image
docker build -t steel-browser:local .
docker run --rm -it -p 3000:3000 -p 9223:9223 steel-browser:local

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

Production Configuration

yaml

services:
  api:
    image: ghcr.io/steel-dev/steel-browser-api:sha256:...
    restart: always
    ports:
      - "3000:3000"
    deploy:
      resources:
        limits:
          memory: 2G
    volumes:
      - ./data/.cache:/app/.cache
    networks:
      - steel-network

Ports Reference

Port	Service	Purpose
3000	API	Browser control and CDP services
5173	UI	Frontend interface
9223	Chrome	Chrome DevTools Protocol debugging

Security Considerations

Never expose port 9223 to the public internet
Set up proper authentication if deploying publicly
Use a reverse proxy with HTTPS for production
Keep containers updated regularly

Updating

bash

docker compose pull
docker compose up -d

Verification Checklist

[ ] Docker version 20.10+ installed
[ ] Containers running: docker ps
[ ] Health check passes: curl localhost:3000/api/health
[ ] UI accessible in browser
[ ] Chrome debugging port not publicly exposed

Troubleshooting

Issue	Solution
Chrome won't start	Check RAM (need 4GB+), check `docker logs`
ARM architecture errors	Use official ARM images or build from source
UI can't connect to API	Verify both containers on same network
Permission errors	Check `.cache` directory permissions

SOP 009: Self-Host with Docker ​

Overview ​

Prerequisites ​

Deployment Decision ​

Option A: Single Docker Image (Simplest) ​

Option B: Docker Compose ​

Step 1: Create Project Directory ​

Step 2: Create docker-compose.yaml ​

Step 3: Launch ​

Step 4: Verify ​

Build from Source ​

Production Configuration ​

Ports Reference ​

Security Considerations ​

Updating ​

Verification Checklist ​

Troubleshooting ​

See Also ​

SOP 009: Self-Host with Docker

Overview

Prerequisites

Deployment Decision

Option A: Single Docker Image (Simplest)

Option B: Docker Compose

Step 1: Create Project Directory

Step 2: Create docker-compose.yaml

Step 3: Launch

Step 4: Verify

Build from Source

Production Configuration

Ports Reference

Security Considerations

Updating

Verification Checklist

Troubleshooting

See Also