Obscura Production Deployment — Docker, Systemd, Workers, and Tuning
Complete production deployment guide for Obscura. Docker image, Systemd service, multi-process workers, V8 heap tuning, reverse proxy, and security.
16Yun Engineering TeamJul 6, 20262 min read
From Dev to Production
Running obscura fetch locally is straightforward. Production requires process management, resource isolation, monitoring, and scaling.
Docker
Based on distroless/cc (no shell, no package manager), ~57 MB compressed.
docker run -d \
--name obscura \
--restart unless-stopped \
-p 127.0.0.1:9222:9222 \
-v /srv/obscura/data:/data \
h4ckf0r0day/obscura \
serve --host 0.0.0.0 --storage-dir /data --stealth
```bash
Resource limits:
```bash
docker run -d \
--name obscura \
--memory=4g \
--cpus=2 \
-p 127.0.0.1:9222:9222 \
h4ckf0r0day/obscura
```bash
## Systemd
```ini
# /etc/systemd/system/obscura.service
[Unit]
Description=Obscura headless browser
After=network.target
[Service]
ExecStart=/usr/local/bin/obscura serve \
--port 9222 --stealth --storage-dir /var/lib/obscura
Restart=always
RestartSec=5
User=obscura
Group=obscura
LimitNOFILE=65536
MemoryMax=4G
MemoryHigh=3G
[Install]
WantedBy=multi-user.target
```bash
## Multi-Worker Scaling
`obscura serve --workers N` spawns N **processes** (not threads):
```bash
obscura serve --workers 4
```bash
Each worker is a separate process with sequential ports starting from port+1. A built-in load balancer distributes connections in round-robin. Sessions are sticky to one worker.
Recommended: workers = CPU cores.
## V8 Heap Tuning
Default heap settings by architecture:
| Architecture | `max-old-space-size` | Other defaults |
|-------------|----------------------|----------------|
| 64-bit | 4096 MB | `--max-semi-space-size=4 --optimize-for-size` |
| Non-64-bit | 1024 MB | `--max-semi-space-size=4 --optimize-for-size` |
Override:
```bash
obscura serve --v8-flags "--max-old-space-size=2048"
```bash
## Reverse Proxy (Nginx)
```nginx
location /obscura/ {
proxy_pass http://127.0.0.1:9222/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400;
}
```bash
## Security
Obscura has no built-in auth. Anyone who can reach the port can drive the browser.
- Bind to `127.0.0.1` by default
- Use Docker network isolation
- Put behind an authenticating reverse proxy
- Never bind `0.0.0.0` on a public IP without auth
MCP HTTP security:
```bash
OBSCURA_MCP_ALLOWED_ORIGINS="https://app.16yun.cn" \
obscura mcp --http --host 0.0.0.0
```bash
## Timeout Tuning
```bash
export OBSCURA_NAV_TIMEOUT_MS=60000
export OBSCURA_CDP_COMMAND_TIMEOUT_MS=30000
export OBSCURA_FETCH_TIMEOUT_MS=20000
obscura serve
```bash
## Observability
```bash
obscura serve --verbose
RUST_LOG=obscura=debug obscura serve
RUST_LOG=obscura_cdp=trace,obscura_browser=debug obscura serve
```bash
## Production Checklist
1. Auto-restart configured (Docker restart or Systemd)
2. Resource limits set (MemoryMax, LimitNOFILE)
3. V8 heap tuned for page workload
4. Reverse proxy handles WebSocket + long timeouts
5. Ports only exposed to trusted networks
6. Stealth mode enabled
7. Storage directory configured
8. Log rotation in place
9. Worker count tested for expected concurrency
## Summary
Production deployment of Obscura is similar to standard web services, with key differences: WebSocket long-connection proxy configuration, multi-process worker scaling, and V8 heap tuning based on page load characteristics.Need an enterprise proxy plan?
We can tailor architecture to your target domains, concurrency, and reliability goals.