screeenly turns a URL into a screenshot through a small Laravel API

A screenshot API, and what it is not

screeenly is an open source web application which lets users create website screenshots through a simple API, and it is built with Laravel.

The product shape is a service, not a library. You send it a URL and it returns an image, which means the interesting engineering is in the rendering pipeline and in the queue that drives it, not in the API surface.

The readme also flags that a completely new version of screeenly has recently been released, at a separate address, and that the app has been rebuilt from the ground up. The new app can also convert websites into PDFs, return the rendered HTML of a website, and it works for your own provided HTML code. It also allows many more settings, such as pixel density and whether images should be loaded.

That distinction matters for anyone reading the repository today. The code in this repository is the older product, and the newer one is a paid subscription where the subscription covers server costs and maintenance. The maintainer states that the open source version hosted on screeenly.com will remain available for the forseeable future, and that registered users will receive notice if anything changes. The repository itself was expected to get updates for Laravel 7 and Laravel 8.

Puppeteer behind a Laravel front end

The two halves of the stack are visible in the package manifest, and they are the reason the application needs a real server rather than shared hosting.

The PHP side is Laravel, with the standard entry points in the repository: an artisan file, a bootstrap directory, a config directory, a routes directory, a database directory and a server.php. The JavaScript side is where the rendering happens, and the dependencies make that explicit: puppeteer at version 5, which is the headless Chrome driver, plus laravel-mix-purgecss, bootstrap-sass, jquery and turbolinks.

Laravel Mix handles the front end build, with a dev script, a watch script, a hot script for hot module replacement, and a production script that runs webpack with the mix configuration. The production build also has a purgecss step, which strips unused CSS.

The important architectural point is that Puppeteer runs on the server. The PHP application receives the request, hands the URL to a headless Chrome instance, and returns the rendered image. That means the deployment has to be able to run a browser, which is the single biggest constraint on self hosting and the reason the environment file has a switch for disabling the Chrome sandbox.

The environment file, and the three settings that decide how it runs

The .env.example is the best description of what this application actually needs, and three of its entries are worth calling out.

The first group is the screeenly specific block, which looks like this:

# Disable Chrome's Sandbox feature
# More information: https://github.com/stefanzweifel/screeenly/issues/174#issuecomment-423438612
SCREEENLY_DISABLE_SANDBOX=false
SCREEENLY_DISK=public
SCREEENLY_USE_AWS_LAMBDA_BROWSER=false

The first of those is SCREEENLY_DISABLE_SANDBOX, defaulting to false, with a comment above it that tells you to disable Chrome's sandbox feature and a link to an issue explaining more. The sandbox is a browser security boundary, and in a container without the right privileges Chrome will not start with it enabled. That single flag is the difference between a working Docker deployment and one that will not start.

The second is SCREEENLY_USE_AWS_LAMBDA_BROWSER, also defaulting to false, which points at a second rendering backend.

The third is SCREEENLY_DISK, set to public, which is where the generated images are written.

The rest is a Laravel environment file with the usual shape: an app key that is empty and has to be generated, debug on, a MySQL connection to localhost, file cache and file sessions with a 120 minute lifetime, a synchronous queue driver, a Redis host and port for anyone who wants it, and a mail section where the comment is explicit that valid mail credentials are required for the password reset flow.

The GitHub OAuth section is for sign-in, with a client id, a secret, a redirect URL, and a comment telling you to create an OAuth application in the GitHub settings. The sidecar block holds the access key, secret, region, artifact bucket name and execution role for a storage sidecar, and the misc section has a Sentry DSN and the filesystem driver.

Self hosting, and the deploy buttons

The readme is blunt about the hosting requirement: screeenly is quite a simple PHP app, so it is quite easy to self host the application on your own server. If you are comfortable running your own server there is a self hosting guide, and the requirements and install page covers it.

For everyone else there are two one-click paths, and the readme links a guide for each.

Deploying to Zeet is described as making it dead simple, and the guide linked is the Heroku one, which walks you through the configuration needed. Deploying to Heroku uses the standard button, and the documentation says that by using Heroku you can run your own version of screeenly basically for free.

Those two deployment paths are the reason the repository has an app.json and a Procfile at the top level, since Heroku needs a manifest to know what to run and a Procfile to say which process type it is. The presence of a modules directory is also a Laravel convention for larger applications, where the code is split into self contained modules rather than living entirely under app.

The Docker route is the third option, and it comes with a caveat. The images are daily built by a community contributor, hosted on Docker Hub with the Dockerfile on GitLab, and the readme states plainly that no support is provided for these Docker images.

Documentation, licensing and the security route

The documentation lives in the wiki, with two pages linked from the readme: the API specification under Use the API, and a page about the code structure called Read the Code.

The second one is the more interesting of the two for an adopter, because it is the only indication in the readme of how the code is arranged, and it is a pointer to a wiki page rather than a summary. Combined with the repository layout, the picture is a conventional Laravel application: an app directory with the application code, a modules directory for larger features, a database directory for migrations and seeds, resources for views and translations, a public directory for the served assets including the generated screenshots, a storage directory for logs and cached files, and a tests directory.

The licence is MIT, and the security policy is stated directly rather than left to a separate file. If you discover a security vulnerability within this package, please e-mail the address given, and all security vulnerabilities will be promptly addressed.

The repository also carries a CLAUDE.md and a CODE_OF_CONDUCT.md, a .php_cs configuration for the code style fixer, a phpunit.xml for the test suite, a .github directory with a Tests workflow that the badge points at, and a CHANGELOG and a readme-image.png. The release history shows v2.0.0 from 2017-02-11, v1.2.1 and v1.2.0 both from 2016-02-22, and the homepage of the hosted service is secure.screeenly.com.

Editorial conclusion

Adopt screeenly if you want a self hosted screenshot service for a website you control and you are happy running a PHP application that shells out to a headless Chrome. Do not adopt it expecting the newer feature set, because the paid successor adds PDF conversion and rendered HTML output that this version does not have. Before you install, check three things: that the headless browser can run in your environment, since the sandbox has to be disabled for it to work, that you configure a real mail transport for the password reset flow, and that the storage and database settings in the environment file are what you want, since the defaults are development values for a local machine.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. stefanzweifel/screeenly on GitHub