Skip to content

Docs Self-hosting

Rendering

Choose and tune the renderer, Browserless or Browsershot, and make sure that it can load fonts and images.

Snapsbrew builds an HTML document for each snap. Headless Chrome opens this document and returns an image or a PDF. RENDER_DRIVER selects how the app reaches Chrome.

Driver How it works Default in
browserless The app sends the HTML over HTTP to a Browserless service. One warm Chrome serves every render. Docker (docker-compose.yml)
browsershot The app starts Node, Puppeteer and a local Chrome for each render. .env.example and the config default

The same driver also captures the screenshots of web pages. Read Screenshots.

Browserless

The app sends a POST request to /screenshot or /pdf on BROWSERLESS_URL. The request holds the HTML, the canvas size and the output type. Browserless returns the raw bytes of the image or the PDF.

.env

RENDER_DRIVER=browserless
BROWSERLESS_URL=http://browserless:3000
BROWSERLESS_TOKEN=<token>
BROWSERLESS_TIMEOUT=60
Variable What it does
BROWSERLESS_URL The base URL of the service. In Docker it is http://browserless:3000. If the app runs on the same host outside Docker, use http://127.0.0.1:3000.
BROWSERLESS_TOKEN The token. The app adds it to each request.
BROWSERLESS_TIMEOUT The timeout of one request, in seconds. Default 60.

Retries

The app tries each Browserless request up to 3 times. It waits 200 ms after the first failure and 400 ms after the second. After the third failure, the app writes a warning to the log and the snap gets the status failed. The app never stores an empty image.

Run Browserless without the main stack

deploy/browserless/docker-compose.yml runs Browserless alone, for a server that runs the app without Docker:

Terminal

export BROWSERLESS_TOKEN=$(openssl rand -hex 24)
docker compose -f deploy/browserless/docker-compose.yml up -d
curl "http://127.0.0.1:3000/json/version?token=$BROWSERLESS_TOKEN"

The last command makes sure that Chrome answers.

Tune Browserless

These variables belong to the Browserless container, not to the app:

Variable In docker-compose.yml In deploy/browserless What it does
CONCURRENT 5 10 The number of renders at the same time. Keep it in line with the Horizon worker count.
QUEUED 20 20 The number of requests that wait for a free slot.
TIMEOUT 60000 60000 The limit of one render, in milliseconds. Keep it in line with BROWSERLESS_TIMEOUT of the app (in seconds).
MAX_MEMORY_PERCENT not set 80 Browserless starts Chrome again above this memory use.
MAX_CPU_PERCENT not set 90 The CPU limit of Browserless.

Use a fixed image tag, for example ghcr.io/browserless/chromium:v2.38.1, and never latest. A new Browserless major version can change the /screenshot payload. Change the tag only together with the renderer code.

WARNING: Do not publish the Browserless port to the internet. The token is its only protection. A person with the token can control the browser and read files through file:// URLs.

Browsershot

Browsershot starts a new Chrome for each render. It is slower and uses more memory than Browserless. It needs no extra service, so it is the default for local development.

.env

RENDER_DRIVER=browsershot
BROWSERSHOT_NODE_PATH=/usr/local/bin/node
BROWSERSHOT_NPM_PATH=/usr/local/bin/npm
BROWSERSHOT_INSTANCE=
Variable What it does
BROWSERSHOT_NODE_PATH The Node binary. Default /usr/local/bin/node.
BROWSERSHOT_NPM_PATH The npm binary. Default /usr/local/bin/npm.
BROWSERSHOT_INSTANCE A remote Chrome as host:port. Empty starts a local Chrome.

npm install downloads a Chrome through Puppeteer. If Puppeteer did not download a Chrome, set the Puppeteer variable PUPPETEER_EXECUTABLE_PATH to the path of a local Chrome.

Fonts

The HTML of a snap loads fonts in two ways:

  • A <link> to https://fonts.googleapis.com for the Google Fonts that the layers use.
  • An @font-face rule for each custom font of the company that a layer uses. The URL of the font file is a media URL of the instance.

Chrome must reach fonts.googleapis.com and the media URL of the instance. If Chrome cannot reach a font, the render uses a fallback font. Read Fonts and media.

Images and other assets

Chrome waits until the network is idle before it takes the image. Chrome loads each image from its URL, from the network of the renderer:

  • An image on S3, Spaces, R2 or another public host works.
  • An image on the public disk has a URL that starts with APP_URL. Chrome must reach APP_URL.

Images on localhost

Browserless runs in its own container. Inside that container, localhost is the Browserless container itself. If APP_URL is http://localhost:8080, Browserless cannot load the images and the fonts of the instance. The render then shows empty images or fallback fonts.

To correct this, do one of these:

  • Use a public domain in APP_URL.
  • Use a bucket for MEDIA_DISK. Read Storage.
  • For local development, use RENDER_DRIVER=browsershot.

A self-signed certificate on the media URL has the same effect. Chrome in Browserless does not trust it.

Timeouts and queues

  • A sync render runs in the web request. The request waits until the renderer returns.
  • An async render runs as a ProcessSnap job on the renders queue. Read Queues and Horizon.
  • The Horizon supervisor has a job timeout of 60 seconds and 1 try.

Output formats

  • type: image or pdf.
  • format: png, jpeg or webp. Default png.
  • transparent: true renders without the white page background. It works with png and webp, not with jpeg.

The maximum canvas size is 4000 × 4000 pixels.

Edit this page on GitHub