jasonraimondi / url-to-png

Selfhosted. URL to PNG utility featuring parallel rendering using Playwright for screenshots and with storage caching via Local, S3, or CouchDB

URL to PNG

A URL to PNG generator over HTTP with a fairly simple API accessed via query params passed to the server.

• Generate PNG images from URLs
• Customizable image dimensions and viewport size
• Support for mobile user agent and dark mode rendering
• Caching of generated images
• Allow list for domain-specific requests
• Configurable Playwright options
• Integration with various storage providers (AWS S3, CouchDB, Filesystem)
• Prometheus metrics endpoint

Getting Started

Checkout the docs to getting_started

Docker

Run the following command:

docker run --rm -p 3089:3089 ghcr.io/jasonraimondi/url-to-png

On the hub: Link to DockerHub

Local Serve

Serve the project

git clone https://github.com/jasonraimondi/url-to-png
cd url-to-png
pnpm install
pnpm exec playwright install chromium
pnpm dev

Configuration

Read the full config options

Encryption

Learn about encryption

Metrics

Learn about metrics

url-to-png's Issues

Browsers not being returned to pool on error?

I'm wondering if the browser needs to be returned to the pool if there is an exception? Should this line be in the finally?

url-to-png/src/services/image-render.service.ts

Line 75 in 221817c

await this.browserPool.release(browser);

AWS environment variables names

It would be great to follow the naming conventions for the AWS environment variables names, e.g.

AWS_ACCESS_KEY_ID instead of AWS_ACCESS_KEY
AWS_SECRET_ACCESS_KEY instead of AWS_SECRET_KEY
etc.

Many hosting services provide add-ons that will automatically inject the credentials and usually follow these naming conventions.

Additionally, adding support for AWS_ENDPOINT_URL_S3 would be useful, in order to use S3-compatible services, such as Cloudlfare R2, Backblaze B2, Tigris.

Invalid response returned for some urls.

Here is an example. If I do a request like this:

http://localhost:5000/?url=https%3A%2F%2Ftest.localhost%2Ftest

Then I get HTTP 200 and Content-Type: image/png. But it actually returns the string "false".

Request
Response

You can see that the response has content-length: 5 so it cannot be a valid image. It contains the string "false". But the header says Content-Type: image/png and HTTP 200. This is messed up.

By the way, "test.localhost" is a non-existent domain. The original request to https://test.localhost/test cannot return a HTTP code, because test.localhost cannot be connected and so there is no request to make. But this should never return with HTTP 200.

Forward HTTP resposne codes

When the given URL returns HTTP 404, then the service returns the rendered image with HTTP 200. This is bad, because the caller cannot tell if there was an error or not. Of course, it is possible (in most cases) to do the original GET request and check for HTTP error codes before asking for a rendered PNG. But that is not very efficient.

Could you please change the program to return the original HTTP code for the request? I understand that it may break compatibility with current users, so here is my proposal with full backward compatibility.

1. Add a new response header called "Original-Http-Response-Code" and send the original response there. This won't break compatibility at all.
2. Add a new parameter "abort_on_error=true". When this parameter is set, then return the request with the original HTTP error code, without rendering and sending the PNG file. So if a user only needs PNG images for URLs that have no errors, then this can speed up things. (By "no error" I meant 200,301,302,304 etc. Anything above 400 is an error)

Screenshots using webp

This might be blasphemy, but having an option for screenshots in webp would be pretty sweet.

memory not freed after each request

the captures of each pages are stored in the memory and are not freed therefore usable in production
it is preferable to close() image buffer after each request

build docker images for arm64

~ ❯❯❯ docker run --rm -p 3000:3000 ghcr.io/jasonraimondi/url-to-png
Unable to find image 'ghcr.io/jasonraimondi/url-to-png:latest' locally
latest: Pulling from jasonraimondi/url-to-png
docker: no matching manifest for linux/arm64/v8 in the manifest list entries.

Docker hub status check

Hi Jason,
I noticed that you have already made some changes on the master branch and have released at least 2 versions. However, the Docker Hub was not updated and the latest tag in Docker Hub is the image for arm devices.
Is this intentional?

Support for local disk caching

A great addition would be the option for caching the results locally, as it would be always faster and more secure than external services like S3 and CouchDB.

Hangs on invalid urls

I'm using url-to-png to create snapshots in my Django web app for a database of web properties; some of which are no longer around.

If I invoke the docker image with this old and now defunked URL:
http://localhost:3000/?url=http://www.greytdogsagility.com

The container gives this error:
error: Attempted to send payload of invalid type 'boolean'. Expected a string or Buffer.

and the connection hangs "forever" and never times out.

Consider using deno

https://github.com/lino-levan/astral

Configurable defaults

All the query parameters have default values! It would be great if these defaults can be configured with environment variables, e.g. DEFAULT_WIDTH, DEFAULT_VIEWPORT_HEIGHT, etc.

GitHub Sponsors is not on

Thank you for making this straightforward tool.

With it, I was able to get a Visionect Place & Play 13 ePaper display to show reasonably complex & modern sites.

Please consider turning on GitHub Sponsors. Things like this make the web go 'round.

add `deviceScaleFactor` support

puppeteer support deviceScaleFactor for high resolution screenshot. can we support that parameter?

I notice that maybe we can change this line: https://github.com/jasonraimondi/url-to-png/blob/master/src/services/image-render.service.ts#L62

Support for hashing the URL params

For security reasons, it would be great to have the option to encode the URL params with a salt string.

So instead of the URL like

http://localhost:3000?url=https://jasonraimondi.com&isFullPage=true&isMobile=true&width=400&height=400&viewPortHeight=400&viewPortWidth=400

One will get something like

http://localhost:3000?hash=dXJsPWh0dHBzOi8vamFzb25yYWltb25kaS5jb20maXNGdWxsUGFnZT10cnVlJmlzRnVsbFBhZ2U9dHJ1ZSZpc01vYmlsZT10cnVlJndpZHRoPTQwMCZoZWlnaHQ9NDAwJnZpZXdQb3J0SGVpZ2h0PTQwMCZ2aWV3UG9ydFdyaXRlPTQwMA==

The salt string can be shared between the app that generates the URL, e.g. you website and the url-to-png service for decoding, while rejecting invalid hashes. This will help preventing abuse since people won't be able to make requests with huge width/height values or pointing the service to malicious websites.