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