HTML to PNG Server

by Adam Hooper <adam@adamhooper.com>

PURPOSE

This program accepts HTML and outputs PNG representations of it.

FEATURES

- Runs as an HTTP server on port 20558
- Renders with multiple strategies:
  - Internet Explorer on Windows
  - Gecko on Ubuntu Linux
  - Firefox 3.0 and above on all platforms
- Can crop images from different rendering strategies so their outputs
  correspond, ideally pixel-for-pixel.

REQUIREMENTS

You must have a Java 6.0 runtime available. Individual rengering strategies
have thier own requirements. (Peruse their source code for details.)

USAGE

This server is intended for a distributed environment (or, at least, an
environment which you foresee to be distributed in the future.) The server
should be run on each "renderer" node--that is, the computer which will
perform the actual rendering, as opposed to the client which will manipulate
those results.

To start the server: java -jar /path/to/html_to_png_server.jar

A client may request a PNG from the server by sending a utf-8 POST request to
"http://node.domain.or.ip.address:20558/STRATEGY", where "STRATEGY" is one of
"ff3-linux", "ie", or anything else registered in HtmlToPngHttpServer.java. The
POST request should consist exclusively of utf8-encoded HTML; the server will
respond with PNG data.

CLIENTS

Known clients include:

- html_render, by Adam Hooper
  http://github.com/adamh/html_render/tree/master
    A Ruby library which provides an API to html_to_png_server (including
    multi-threaded, distributed rendering) with special classes for integrating
    with unit testing libraries.

STRATEGIES

  IE (http://server/ie)

  how it works: it extracts a custom executable into a temporary directory and
                executes it.
  requires: .NET 2.0 platform or above
  how it could improve:
    - it could be sped up
    - it could be made to work without logging on (for a graphics context)
    - its license could be clarified (it is a copy/paste mix-and-match from
      Internet forums)
  tips: use a different computer (or virtual machine) for each different
        version of Internet Explorer.

  GECKO ON LINUX (http://server/ff3-linux)

  how it works: it executes "gnome-web-photo", assumed to be in the user's path
  requires: the "gnome-web-photo" Ubuntu package (or equivalent)
  how it could improve:
    - it could be sped up
  tips: run this Java server in an Xvfb instance to avoid the need to log in
        (for instance, "xvfb-run java -jar html_to_png_server/html_to_png_server.jar")

  FIREFOX THROUGH MOZREPL (http://server/mozrepl)

  how it works: it acts (kind of) like a proxy to a MozRepl screenshot server.
  requires: "mozrepl" Firefox extension - http://wiki.github.com/bard/mozrepl
  installation:
    1. Install "mozrepl" from http://wiki.github.com/bard/mozrepl
    2. Copy vendor/moz-repl-screenshot-server.js somewhere local and permanent
    3. Open Firefox and browse to "about:config"
    4. Set "extensions.mozrepl.defaultInteractor" to "screenshot"
    5. Set "extensions.mozrepl.initUrl" to
       "file:///.../moz-repl-screenshot-server.js" (where "..." is the location
       you chose to save the file in Step 2).
    6. Set "extensions.mozrepl.autoStart" to "true"
    7. Click Tools -> MozRepl -> Start
       path you chose to save 
  how it could improve:
    - installation could be made simpler
    - it could be made not to require a running Firefox instance
    - it could be made to work without logging on (for a graphics context). (On
      UNIX-like systems, at least, "xvfb-run" can circumvent this.)

  SAFARI ON OS X (http://server/webkit2png)

  how it works: it extracts webkit2png into a temporary directory and executes
                it. See http://github.com/paulhammond/webkit2png
  requires: See http://github.com/paulhammond/webkit2png
            - On OSX, use "Java Preferences" and ensure you are on Java 6
            - Aside from that, everything should work by default
            - OSX is notoriously difficult to run in a VM, so "a Mac" is one of
              the requirements
  how it could improve:
    - it could be sped up
    - it could be made to work without logging on (for a graphics context)

DEVELOPMENT

The code is fairly (though by no means expertly) organized, though cut/pasted
too heavily. Open this folder in Eclipse and enjoy yourself.

Feel free to send me any patches, generated through "git format-patch" or,
slightly less helpfully, "diff -u". I will concern myself with regenerating
"ie-thumbnail-generator.exe" and "html_to_png_server.jar".

As far as I can see, the client/server API will not change. As for this
server's internals: no APIs should be considered stable.

LICENSE

I believe in software freedom, and that includes the freedom for that software
to be relicensed or otherwise taken out of my control. This code is all
released under the Public Domain, or as to Public Domain as is legally
sensible. I declare myself absolved of my copyright on this code.

Exception: Files in the vendor/ directory were not written by me; I have tried
to faithfully copy their licenses here.