README.rst

   1 ************************************
   2 phancap - website screenshot service
   3 ************************************
   4
   5 Web service (API) to create website screenshots.
   6
   7 Self-hosted and written in PHP. Caching included.
   8
   9
  10 *phancap* is useful for:
  11
  12 - Show screenshots for websites in your bookmarking application
  13 - Archive a HTML page as PDF for later viewing
  14
  15
  16 .. contents::
  17
  18
  19 ========
  20 Features
  21 ========
  22
  23 * Configurable browser size
  24 * Configurable screenshot size
  25 * Clip and full page rendering (full height)
  26 * JPG, PNG and PDF output (PDFs are searchable)
  27 * Authentication
  28 * Can run on a normal web server without GUI. See dependencies_.
  29
  30
  31 .. note::
  32     *phancap* does not rely on a "real" browser.
  33     Currently ``cutycapt`` is utilized, which uses a pretty bare webkit to render
  34     the pages.
  35     Do not expect pixel-for-pixel identical rendering as your desktop browser.
  36
  37
  38 ===============
  39 Getting started
  40 ===============
  41
  42 Basic setup
  43 ===========
  44 #. Download the ``.phar`` file and put it onto your web server
  45 #. Open the phar file in your browser
  46 #. Click the "setup check" link
  47 #. Fix all errors that are reported
  48 #. Run ``phancap.phar/get.php?url=cweiske.de`` and see the screenshot
  49
  50
  51 Advanced setup
  52 ==============
  53 With the basic setup, everyone may use your server to create website
  54 screenshots.
  55 You may want to change that or simply change some default settings.
  56
  57 #. Create a config file ``phancap.phar.config.php``
  58 #. Edit it; see the configuration_ options.
  59
  60
  61 ==============
  62 URL parameters
  63 ==============
  64 ``get.php`` supports the following parameters:
  65
  66 Browser parameters
  67 ==================
  68 ``url``
  69   Website URL
  70 ``bwidth``
  71   Browser width (default: 1024)
  72 ``bheight``
  73   Browser height (default: none)
  74
  75 Screenshot parameters
  76 =====================
  77 ``swidth``
  78   Screenshot width (default: none (no scaling))
  79 ``sheight``
  80   Screenshot height (default: none)
  81 ``sformat``
  82   Screenshot format (``png``, ``jpg``, ``pdf``, default: ``png``)
  83 ``smode``
  84   Screenshot mode (``screen`` (4:3) or ``page`` (full website height))
  85 ``smaxage``
  86   Maximum age of screenshot in seconds.
  87   ISO 8601 duration specifications accepted:
  88
  89   - ``P1Y`` - 1 year
  90   - ``P2W`` - 2 weeks
  91   - ``P1D`` - 1 day
  92   - ``PT4H`` - 4 hours
  93
  94   The configuration file defines a minimum age that the user cannot undercut
  95   (``$screenshotMinAge``), as well as a default value (``$screenshotMaxAge``).
  96
  97 Authentication parameters
  98 =========================
  99 ``atimestamp``
 100   Time at which the request URL was generated (unix timestamp)
 101 ``atoken``
 102   Access token (username)
 103 ``asignature``
 104   Signature for the request. See the authentication_ section.
 105
 106
 107 =============
 108 Configuration
 109 =============
 110 phancap looks at several places for its configuration file:
 111
 112 #. ``phancap.phar.config.php`` in the same directory as your
 113    ``phancap.phar`` file.
 114
 115 #. ``/etc/phancap.php``
 116
 117
 118 Configuration variables
 119 =======================
 120 ``$cacheDir``
 121   Full file system path to image cache directory
 122 ``$cacheDirUrl``
 123   Full URL to cache directory
 124 ``$access``
 125   Credentials for access control
 126
 127   ``true`` to allow access to anyone, ``false`` to disable it completely.
 128   ``array`` of username - secret key combinations otherwise.
 129 ``$cutycapt['parameters']``
 130   Additional command line parameters for cutycapt.
 131   Can be used to e.g. enable browser plugins:
 132
 133   ``$cutycapt['parameters'] = '--plugins=on';``
 134 ``$cutycapt['maxWaitTime']``
 135   Maximal time in seconds to wait for cutycapt to finish rendering.
 136   Defaults to 30 seconds.
 137 ``$disableSetup``
 138   Disable ``setup.php`` which will leak file system paths
 139 ``$redirect``
 140   Redirect to static image urls after generating them
 141 ``$timestampmaxAge``
 142   How long a signature timestamp is considered valid. 2 days default.
 143 ``$screenshotMaxAge``
 144   Cache time of downloaded screenshots.
 145
 146   When the file is as older than this, it gets re-created.
 147 ``$screenshotMinAge``
 148   Minimum age of a screeshot. 1 hour default.
 149
 150   A user cannot set the max age parameter below it.
 151
 152
 153
 154 ==============
 155 Authentication
 156 ==============
 157 Creating screenshots of websites is a resource intensive process.
 158 To prevent unauthorized access to the service, phancap supports authentication
 159 via a signature parameter similar to OAuth's ``oauth_signature``.
 160
 161 Phancap's configuration file may contain a ``$access`` variable:
 162
 163 ``true``
 164   Everyone is allowed to access the service
 165 ``false``
 166   Nobody is allowed to access the service
 167 ``array``
 168   A list of usernames that are allowed to request screenshots, together
 169   with their secret keys (password)::
 170
 171     $access = array(
 172        'user1' => 'secret1',
 173        'user2' => 'secret2',
 174     )
 175
 176 The signature algorithm is as follows:
 177
 178 #. Parameters ``atimestamp`` (current unix timestamp) and
 179    ``atoken`` (username) have to be added to the URL parameters
 180
 181 #. URL parameters are normalized as described in
 182    `OAuth Parameters Normalization`__:
 183
 184    #. Sort parameters list by name
 185    #. Name and value are `raw-url-encoded`__
 186    #. Name and value are concatenated with ``=`` as separator
 187    #. The resulting strings are concatenated with ``&`` as separator
 188
 189 #. URL parameter string is used together with the secret key
 190    to create a `HMAC-SHA1`__ digest
 191
 192 #. Digest is appended to the URL as ``asignature``
 193
 194 __ http://tools.ietf.org/html/rfc5849#section-3.4.1.3.2
 195 __ http://tools.ietf.org/html/rfc5849#section-3.6
 196 __ http://tools.ietf.org/html/rfc5849#section-3.4.2
 197
 198
 199 Example
 200 =======
 201
 202 .. note::
 203
 204     The ``docs/`` directory contains an example PHP client implementation.
 205
 206 We want to create a screenshot of ``http://example.org/`` in size 400x300,
 207 using the browser size of 1024x768::
 208
 209     http://example.org/phancap/get.php?swidth=400&sheight=300&url=http%3A%2F%2Fexample.org%2F&bwidth=1024&bheight=768
 210
 211 Phancap's config file contains::
 212
 213     $access = array(
 214         'user' => 'secret'
 215     );
 216
 217 Our parameters are thus:
 218
 219 ============== =====
 220 Name           Value
 221 ============== =====
 222 ``swidth``     ``400``
 223 ``sheight``    ``300``
 224 ``url``        ``http://example.org/``
 225 ``bwidth``     ``1024``
 226 ``bheight``    ``768``
 227 ============== =====
 228
 229 At first, we need to add parameters ``atimestamp`` and ``atoken``.
 230 ``atimestamp`` is the current unix timestamp.
 231 ``atoken`` is our user name: ``user``.
 232
 233 Now the parameter list is sorted:
 234
 235 ============== =====
 236 Name           Value
 237 ============== =====
 238 ``atimestamp`` ``1396353987``
 239 ``atoken``     ``user``
 240 ``bheight``    ``768``
 241 ``bwidth``     ``1024``
 242 ``sheight``    ``300``
 243 ``swidth``     ``400``
 244 ``url``        ``http://example.org/``
 245 ============== =====
 246
 247 The parameters are raw-url-encoded. The only value that changes is the url,
 248 it becomes ``http%3A%2F%2Fexample.org%2F``.
 249
 250 Concatenating the name/value pairs leads to the following string::
 251
 252     atimestamp=1396353987&atoken=user&bheight=768&bwidth=1024&sheight=300&swidth=400&url=http%3A%2F%2Fexample.org%2F
 253
 254 Creating the HMAC digest with sha1, the calculated string and our key
 255 ``secret`` gives us the following string::
 256
 257     9a12eac5ff859f9306eaaf5a18b9a931fe10b89d
 258
 259 This is the signature; it gets appended to the URL as ``asignature`` parameter.
 260
 261
 262 ============
 263 Dependencies
 264 ============
 265 - External tools:
 266
 267   - `cutycapt <http://cutycapt.sourceforge.net/>`_
 268   - `imagemagick's <http://www.imagemagick.org/>`_ ``convert``
 269   - ``xvfb-run``
 270
 271 - Libraries (already included in the ``.phar``):
 272
 273   - PEAR's ``System.php``
 274
 275
 276 =======
 277 License
 278 =======
 279 ``phancap`` is licensed under the `AGPL v3`__ or later.
 280
 281 __ http://www.gnu.org/licenses/agpl.html
 282
 283
 284 ========
 285 Homepage
 286 ========
 287 Web site
 288    http://cweiske.de/phancap.htm
 289
 290 Source code
 291    http://git.cweiske.de/phancap.git
 292
 293    Mirror: https://github.com/cweiske/phancap
 294
 295
 296 ======
 297 Author
 298 ======
 299 Written by Christian Weiske, cweiske@cweiske.de
 300
 301
 302 ============
 303 Alternatives
 304 ============
 305 All of those are open source:
 306
 307 * http://code.google.com/p/browsershots/ (python)
 308 * https://github.com/gre/screenshot-webservice (scala)