Skip to content

Latest commit

 

History

History
555 lines (403 loc) · 12.2 KB

FAQ.md

File metadata and controls

555 lines (403 loc) · 12.2 KB

Frequently Asked Questions (FAQ)

General Questions

What is Open Browser Rendering?

Open Browser Rendering is a self-hosted, open-source alternative to Cloudflare Browser Rendering API. It allows you to capture screenshots, generate PDFs, and execute JavaScript in a headless browser environment via a simple REST API.

How is this different from Cloudflare Browser Rendering?

  • Self-hosted: You control your infrastructure and data
  • Open-source: Free to use, modify, and contribute
  • No vendor lock-in: Deploy anywhere you want
  • Customizable: Modify the code to fit your needs
  • Cost-effective: No per-request pricing

What browsers are supported?

  • Chromium (default, recommended)
  • Firefox
  • WebKit

You can switch between browsers using the BROWSER_ENGINE environment variable.

Installation & Setup

What are the system requirements?

  • Node.js: >= 18.0.0
  • RAM: Minimum 2GB (4GB+ recommended for production)
  • CPU: 2+ cores recommended
  • Disk: 2GB+ for browser binaries and dependencies

Can I run this on Windows?

Yes! The service runs on Windows, macOS, and Linux. However, Docker deployment is recommended for production use.

Do I need Docker?

No, Docker is optional. You can run the service directly with Node.js. However, Docker is recommended for:

  • Easier deployment
  • Consistent environment
  • Better resource management
  • Simplified updates

How do I install Playwright browsers?

If running without Docker:

npx playwright install --with-deps

Docker images already include browsers.

Configuration

How do I change the API key?

Edit the .env file:

RENDERER_API_KEY=your-secure-key-here

Or set environment variable:

export RENDERER_API_KEY=your-secure-key-here

What is the recommended MAX_CONCURRENCY?

Based on available RAM:

  • 2GB RAM: MAX_CONCURRENCY=2
  • 4GB RAM: MAX_CONCURRENCY=4
  • 8GB RAM: MAX_CONCURRENCY=8
  • 16GB+ RAM: MAX_CONCURRENCY=16

How do I enable CORS for specific domains?

Edit .env:

ALLOWED_ORIGINS=https://example.com,https://app.example.com

Can I use multiple browser engines simultaneously?

No, you can only use one browser engine at a time. Set BROWSER_ENGINE to your preferred engine.

Usage

How do I capture a full-page screenshot?

Set fullPage: true in screenshotOptions:

{
  "url": "https://example.com",
  "screenshotOptions": {
    "fullPage": true
  }
}

Can I capture screenshots of authenticated pages?

Not directly. The API doesn't support cookies or authentication headers. You would need to:

  1. Modify the code to accept cookies
  2. Use the /evaluate endpoint to handle login
  3. Use a session management solution

What image formats are supported for screenshots?

  • PNG (default, lossless)
  • JPEG (with quality control)

What PDF paper sizes are supported?

  • Letter
  • Legal
  • Tabloid
  • Ledger
  • A0, A1, A2, A3, A4, A5, A6

How long can a page take to load?

Default timeout is 30 seconds. You can adjust this with gotoOptions.timeout (in milliseconds):

{
  "url": "https://example.com",
  "gotoOptions": {
    "timeout": 60000
  }
}

What does "waitUntil" mean?

It determines when the page is considered loaded:

  • load: Wait for the load event
  • domcontentloaded: Wait for DOMContentLoaded event
  • networkidle: Wait for network to be idle (recommended for dynamic content)

Deployment

Can I deploy this on shared hosting?

Probably not. Shared hosting typically doesn't support:

  • Node.js long-running processes
  • Browser automation
  • Sufficient resources

Use a VPS or cloud server instead.

What VPS providers are recommended?

  • DigitalOcean (Droplet)
  • Linode
  • Vultr
  • AWS EC2
  • Google Cloud Compute Engine
  • Azure Virtual Machines

Minimum: 2GB RAM, 2 vCPU

How do I set up HTTPS?

Use Nginx as a reverse proxy with Let's Encrypt:

sudo apt install nginx certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

See deployment guide in README for details.

Can I use this with Kubernetes?

Yes! You can deploy using Kubernetes. Create a deployment and service:

  • Use the Docker image
  • Set environment variables via ConfigMap/Secret
  • Configure resource limits
  • Set up horizontal pod autoscaling

How do I update to a new version?

Docker:

cd /path/to/OpenBrowserRendering
git pull
docker-compose down
docker-compose up -d --build

PM2:

cd /path/to/OpenBrowserRendering
git pull
npm install
pm2 restart open-browser-rendering

Performance

How many requests can it handle?

Depends on:

  • Server resources (CPU, RAM)
  • Page complexity
  • Screenshot/PDF size
  • Concurrency settings

Typical performance:

  • 2GB RAM: 2-4 concurrent requests
  • 4GB RAM: 4-8 concurrent requests
  • 8GB RAM: 8-16 concurrent requests

How can I improve performance?

  1. Increase MAX_CONCURRENCY (if you have resources)
  2. Use smaller viewport sizes
  3. Disable fullPage when not needed
  4. Use JPEG instead of PNG (smaller file size)
  5. Reduce timeout values
  6. Add more RAM/CPU
  7. Use a queue system for high traffic

Why is it slow?

Common reasons:

  • Page has heavy JavaScript
  • Large images/resources
  • Network latency
  • Insufficient server resources
  • Too many concurrent requests

Try:

  • Increase timeout
  • Use waitUntil: "load" instead of "networkidle"
  • Optimize the target page
  • Upgrade server resources

Troubleshooting

Error: "Too many concurrent requests"

You've hit the MAX_CONCURRENCY limit. Either:

  • Wait and retry
  • Increase MAX_CONCURRENCY (if you have resources)
  • Implement a queue system

Error: "Timeout exceeded"

The page took too long to load. Try:

  • Increase gotoOptions.timeout
  • Check if the URL is accessible
  • Try a different waitUntil option
  • Check network connectivity

Browser crashes or hangs

Usually due to insufficient resources:

  • Increase server RAM
  • Reduce MAX_CONCURRENCY
  • Restart the service
  • Check for memory leaks

Docker container keeps restarting

Check logs:

docker-compose logs -f

Common issues:

  • Insufficient memory
  • Port already in use
  • Invalid configuration
  • Missing environment variables

Screenshots are blank

Possible causes:

  • Page requires JavaScript (use waitUntil: "networkidle")
  • Page blocks headless browsers
  • Authentication required
  • Page has errors

Security

Is it safe to expose this publicly?

Only if you:

  • Use a strong API key
  • Enable HTTPS
  • Implement rate limiting
  • Restrict CORS
  • Monitor for abuse
  • Keep software updated

Should I disable the /evaluate endpoint?

Yes, if you don't need it. The /evaluate endpoint executes arbitrary JavaScript and should only be accessible to trusted users.

To disable, remove the endpoint from server.js.

How do I prevent abuse?

  1. Use strong API key
  2. Implement rate limiting (Nginx, Cloudflare)
  3. Monitor usage
  4. Set up alerts
  5. Use IP whitelisting
  6. Implement request validation
  7. Set resource limits

Contributing

How can I contribute?

See CONTRIBUTING.md for guidelines.

I found a bug, what should I do?

  1. Check if it's already reported in Issues
  2. Create a new issue with details
  3. Include reproduction steps
  4. Provide environment information

I have a feature request

Create a feature request issue with:

  • Problem description
  • Proposed solution It determines when the page is considered loaded:
  • load: Wait for the load event
  • domcontentloaded: Wait for DOMContentLoaded event
  • networkidle: Wait for network to be idle (recommended for dynamic content)

Deployment

Can I deploy this on shared hosting?

Probably not. Shared hosting typically doesn't support:

  • Node.js long-running processes
  • Browser automation
  • Sufficient resources

Use a VPS or cloud server instead.

What VPS providers are recommended?

  • DigitalOcean (Droplet)
  • Linode
  • Vultr
  • AWS EC2
  • Google Cloud Compute Engine
  • Azure Virtual Machines

Minimum: 2GB RAM, 2 vCPU

How do I set up HTTPS?

Use Nginx as a reverse proxy with Let's Encrypt:

sudo apt install nginx certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

See deployment guide in README for details.

Can I use this with Kubernetes?

Yes! You can deploy using Kubernetes. Create a deployment and service:

  • Use the Docker image
  • Set environment variables via ConfigMap/Secret
  • Configure resource limits
  • Set up horizontal pod autoscaling

How do I update to a new version?

Docker:

cd /path/to/OpenBrowserRendering
git pull
docker-compose down
docker-compose up -d --build

PM2:

cd /path/to/OpenBrowserRendering
git pull
npm install
pm2 restart open-browser-rendering

Performance

How many requests can it handle?

Depends on:

  • Server resources (CPU, RAM)
  • Page complexity
  • Screenshot/PDF size
  • Concurrency settings

Typical performance:

  • 2GB RAM: 2-4 concurrent requests
  • 4GB RAM: 4-8 concurrent requests
  • 8GB RAM: 8-16 concurrent requests

How can I improve performance?

  1. Increase MAX_CONCURRENCY (if you have resources)
  2. Use smaller viewport sizes
  3. Disable fullPage when not needed
  4. Use JPEG instead of PNG (smaller file size)
  5. Reduce timeout values
  6. Add more RAM/CPU
  7. Use a queue system for high traffic

Why is it slow?

Common reasons:

  • Page has heavy JavaScript
  • Large images/resources
  • Network latency
  • Insufficient server resources
  • Too many concurrent requests

Try:

  • Increase timeout
  • Use waitUntil: "load" instead of "networkidle"
  • Optimize the target page
  • Upgrade server resources

Troubleshooting

Error: "Too many concurrent requests"

You've hit the MAX_CONCURRENCY limit. Either:

  • Wait and retry
  • Increase MAX_CONCURRENCY (if you have resources)
  • Implement a queue system

Error: "Timeout exceeded"

The page took too long to load. Try:

  • Increase gotoOptions.timeout
  • Check if the URL is accessible
  • Try a different waitUntil option
  • Check network connectivity

Browser crashes or hangs

Usually due to insufficient resources:

  • Increase server RAM
  • Reduce MAX_CONCURRENCY
  • Restart the service
  • Check for memory leaks

Docker container keeps restarting

Check logs:

docker-compose logs -f

Common issues:

  • Insufficient memory
  • Port already in use
  • Invalid configuration
  • Missing environment variables

Screenshots are blank

Possible causes:

  • Page requires JavaScript (use waitUntil: "networkidle")
  • Page blocks headless browsers
  • Authentication required
  • Page has errors

Security

Is it safe to expose this publicly?

Only if you:

  • Use a strong API key
  • Enable HTTPS
  • Implement rate limiting
  • Restrict CORS
  • Monitor for abuse
  • Keep software updated

Should I disable the /evaluate endpoint?

Yes, if you don't need it. The /evaluate endpoint executes arbitrary JavaScript and should only be accessible to trusted users.

To disable, remove the endpoint from server.js.

How do I prevent abuse?

  1. Use strong API key
  2. Implement rate limiting (Nginx, Cloudflare)
  3. Monitor usage
  4. Set up alerts
  5. Use IP whitelisting
  6. Implement request validation
  7. Set resource limits

Contributing

How can I contribute?

See CONTRIBUTING.md for guidelines.

I found a bug, what should I do?

  1. Check if it's already reported in Issues
  2. Create a new issue with details
  3. Include reproduction steps
  4. Provide environment information

I have a feature request

Create a feature request issue with:

  • Problem description
  • Proposed solution
  • Use case
  • Alternative solutions considered

Support

Where can I get help?

Is there commercial support?

This is a community project by DEVMODE Community. For commercial support, consider:

  • Hiring a developer
  • Contributing to the project
  • Sponsoring development

Can I hire someone to set this up?

Yes! You can hire a developer familiar with:

  • Node.js
  • Docker
  • Linux server administration
  • Nginx configuration

Made with ❤️ by DEVMODE Community