Manet

There is only one true thing: instantly paint what you see. When you've got it, you've got it. When you haven't, you begin again. All the rest is humbug.

Manet is a REST API server which allows capturing screenshots of websites using various parameters. It is a good way to make sure that your websites are responsive or to make thumbnails.

Manet could use different engines to work: SlimerJS or PhantomJs.

• SlimerJS runs on top of Gecko (the browser engine of Mozilla Firefox) and SpiderMonkey (the JavaScript engine of Firefox).
• PhantomJS runs on top of WebKit and JavaScriptCore.

Project was named in honor of Édouard Manet, French painter (1832-1883). He was one of the first 19th-century artists to paint modern life, and a pivotal figure in the transition from Realism to Impressionism.

Main features

• Ready-To-Use
• Supporting SlimerJS and PhantomJS
• Configurable CLI application
• Flexible REST API
• File caching
• Various image formats
• Sandbox UI

Setup

Preset

Choose and install needed engine (PhantomJS, SlimerJS, or both of them):

SlimerJS:

• You can download SlimerJS from the official site and install manually.
• or you can use the power of NPM:

npm install -g slimerjs

Gecko, the rendering engine of Firefox, cannot render web content without a graphical window, but you can launch SlimerJS with xvfb if you are under linux or MacOSx, to have a headless SlimerJS, so it is also necessary to install Xvfb (X virtual framebuffer) for *nix or OS X systems.

For example, you can use apt-get to install xvfb on Ubuntu:

sudo apt-get install xvfb

PhantomJS

• You can download PhantomJS from the official site and install manually.
• or you can also use NPM:

npm install -g phantomjs

or (to use second version):

npm install -g phantomjs2

IMPORTANT: PhantomJS is used by default (see default.yaml file).

Installation

After preliminaries operations you can install Manet using NPM:

npm install -g manet

That is all, now you can start and use Manet server. As you can see, it is unnecessary to clone Git repository or something else.

Server launching

Server launching is a simple as possible:

manet

If everything is OK, you should see the following message:

info: Manet server started on port 8891

Server configuration

Manet server uses hierarchical configurations to cover differnet usage use-cases:

• Command-line parameters
• Environment variables
• Built-in configuration YAML file ("config/default.yaml")

Rules of overriding:

• Each configuration level could be overridden by another level.
• The most-priority parameters are command-line parameters.
• The less-priority parameters are stored in build-in configuration file.

CLI parameters

Configuration file

Built-in configuration could be found in manet directory. For example, on Ubuntu it is located here: "/usr/local/lib/node_modules/manet/".

Default configuration file ("default.yaml"):

host: 0.0.0.0
port: 8891
cors: false
ui: true

silent: false
level: info

engine: phantomjs
timeout: 60000
compress: false
cache: 3600
cleanupStartup: false
cleanupRuntime: false

commands:
    slimerjs:
        linux: "xvfb-run -a slimerjs"
        freebsd: "xvfb-run -a slimerjs"
        sunos: "xvfb-run -a slimerjs"
        darwin: "slimerjs"
        win32: "slimerjs.bat"
    phantomjs:
        linux: "phantomjs --ignore-ssl-errors=true --web-security=false"
        freebsd: "phantomjs --ignore-ssl-errors=true --web-security=false"
        sunos: "phantomjs --ignore-ssl-errors=true --web-security=false"
        darwin: "phantomjs --ignore-ssl-errors=true --web-security=false"
        win32: "phantomjs --ignore-ssl-errors=true --web-security=false"

whitelist:
    - "*"

security:
    basic:
#        username: admin
#        password: admin

REST API

REST API is available on "/" using:

• GET method
• POST method with Content-Type:
  • application/json
  • or application/x-www-form-urlencoded

Few rules:

• The "url" parameter must be specified.
• It is possible to send data using query parameters or HTTP Message Body.
• Query parameters will be used in priority and override others.

Available parameters

Query examples

For a quick test with the command line (using curl), type:

curl http://localhost:8891/?url=github.com > github.png
curl -H "Content-Type: application/json" -d '{"url":"github.com"}' http://localhost:8891/ > github.png
curl -H "Content-Type: application/x-www-form-urlencoded" -d 'url=github.com' http://localhost:8891/ > github.png

or (using wget)

wget http://localhost:8891/?url=github.com -O github.png

Here are some query examples that could be executed by any REST API client:

# Take a screenshot of the github.com.
GET /?url=github.com

# Custom viewport size. Return a 800x600 PNG screenshot of the github.com homepage.
GET /?url=github.com&width=800&height=600

# Clipping Rectangle. Return a screenshot clipped at [top=20, left=30, width=90, height=80]
GET /?url=github.com&clipRect=20%2C30%2C90%2C80

# Zoom rendered page in 2 times.
GET /?url=github.com&zoom=2

# Specify image output format.
GET /?url=github.com&format=jpeg

# Disable JavaScript. Return a screenshot with no JavaScript executed.
GET /?url=github.com&js=false

# Disable images. Return a screenshot without images.
GET /?url=github.com&images=false

# Custom User Agent.
GET /?url=github.com&agent=Mozilla%2F5.0+(X11%3B+Linux+x86_64)+AppleWebKit%2F537.36+(KHTML%2C+like+Gecko)+Chrome%2F34.0.1847.132+Safari%2F537.36

# HTTP Basic Authentication. Return a screenshot of a website requiring basic authentication.
GET /?url=mysite.com&user=john&password=smith

# Screenshot delay. Return a screenshot of the github.com homepage 1 second after it's loaded.
GET /?url=github.com&delay=1000

# Force page reloading. Return a screenshot without using file cache.
GET /?url=github.com&force=true

# Wait for a div element with a class name "header" to be available.
GET /?url=github.com&selector=div.header

# Specify custom HTTP headers.
GET /?url=google.com&headers=User-Agent=Firefox;Accept-Charset=utf-8

# Asynchronous call.
GET /?url=github.com&callback=http://localhost:8891

Sandbox UI

Sandbox UI is available on "/" by direct GET request without "url" query parameter. It is a simple playground to build HTTP requests and try them.

Demo instance is available on Heroku: https://manet.herokuapp.com

You can also use "Deploy to Heroku" button to create your own Manet instance on Heroku without leaving the web browser, and with little configuration.

Development

• To install project dependencies:

npm install

• To run jshint checks:

npm run lint

• To run Mocha unit tests:

# using NPM:
npm test
# using mocha and watcher:
mocha --watch -R spec

• To run Manet server:

./bin/manet

Alternative clients

Ruby:

• manet_client is a simple Ruby client library for Manet.

Deployment options

Docker

Docker is an open platform to build, ship, and run distributed applications, whether on laptops, data center VMs, or the cloud.

Manet has some already known Dockerfiles:

• Pietro Delsante provides the first manet-dockerfile to run Manet inside a Docker container.
• Kris Carle provides fork of previous project with WebGL support for SlimerJS.
• Walter Franchetti provides docker-Manet with PhantomJS and libfreetype6.
• Olivier Balais provides docker-manet with extended charactersets such as Japanese and Chinese.

Heroku

First of all read https://devcenter.heroku.com/articles/deploying-nodejs (section "Deploy your application to Heroku"). You need to create Heroku instance with as described in this documentation.

Procfile file for PhantomJS is already existed in root of the project. This file describes Heroku how to start Manet.

SlimerJS does not work on Heroku, because it has not got a headless mode and it is quite complicated to install xvfb on this platform (but you can try your luck).

Thanks to

• SlimerJS author Laurent Jouanneau and SlimerJS community.
• PhantomJS author Ariya Hidayat and PhantomJS community.
• Pietro Delsante, Kris Carle, Walter Franchetti, and Olivier Balais for running project inside a Docker container.
• Felipe JAPM for Ruby client.
• All contributors for their help and pull requests.

Self portrait

One picture more than a thousand words:

License

The MIT License (MIT)

Copyright (c) 2014 Vladislav Bauer (see LICENSE).