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 ``$disableSetup``
 130   Disable ``setup.php`` which will leak file system paths
 131 ``$redirect``
 132   Redirect to static image urls after generating them
 133 ``$timestampmaxAge``
 134   How long a signature timestamp is considered valid. 2 days default.
 135 ``$screenshotMaxAge``
 136   Cache time of downloaded screenshots.
 137
 138   When the file is as older than this, it gets re-created.
 139 ``$screenshotMinAge``
 140   Minimum age of a screeshot. 1 hour default.
 141
 142   A user cannot set the max age parameter below it.
 143
 144
 145
 146 ==============
 147 Authentication
 148 ==============
 149 Creating screenshots of websites is a resource intensive process.
 150 To prevent unauthorized access to the service, phancap supports authentication
 151 via a signature parameter similar to OAuth's ``oauth_signature``.
 152
 153 Phancap's configuration file may contain a ``$access`` variable:
 154
 155 ``true``
 156   Everyone is allowed to access the service
 157 ``false``
 158   Nobody is allowed to access the service
 159 ``array``
 160   A list of usernames that are allowed to request screenshots, together
 161   with their secret keys (password)::
 162
 163     $access = array(
 164        'user1' => 'secret1',
 165        'user2' => 'secret2',
 166     )
 167
 168 The signature algorithm is as follows:
 169
 170 #. Parameters ``atimestamp`` (current unix timestamp) and
 171    ``atoken`` (username) have to be added to the URL parameters
 172
 173 #. URL parameters are normalized as described in
 174    `OAuth Parameters Normalization`__:
 175
 176    #. Sort parameters list by name
 177    #. Name and value are `raw-url-encoded`__
 178    #. Name and value are concatenated with ``=`` as separator
 179    #. The resulting strings are concatenated with ``&`` as separator
 180
 181 #. URL parameter string is used together with the secret key
 182    to create a `HMAC-SHA1`__ digest
 183
 184 #. Digest is appended to the URL as ``asignature``
 185
 186 __ http://tools.ietf.org/html/rfc5849#section-3.4.1.3.2
 187 __ http://tools.ietf.org/html/rfc5849#section-3.6
 188 __ http://tools.ietf.org/html/rfc5849#section-3.4.2
 189
 190
 191 Example
 192 =======
 193
 194 .. note::
 195
 196     The ``docs/`` directory contains an example PHP client implementation.
 197
 198 We want to create a screenshot of ``http://example.org/`` in size 400x300,
 199 using the browser size of 1024x768::
 200
 201     http://example.org/phancap/get.php?swidth=400&sheight=300&url=http%3A%2F%2Fexample.org%2F&bwidth=1024&bheight=768
 202
 203 Phancap's config file contains::
 204
 205     $access = array(
 206         'user' => 'secret'
 207     );
 208
 209 Our parameters are thus:
 210
 211 ============== =====
 212 Name           Value
 213 ============== =====
 214 ``swidth``     ``400``
 215 ``sheight``    ``300``
 216 ``url``        ``http://example.org/``
 217 ``bwidth``     ``1024``
 218 ``bheight``    ``768``
 219 ============== =====
 220
 221 At first, we need to add parameters ``atimestamp`` and ``atoken``.
 222 ``atimestamp`` is the current unix timestamp.
 223 ``atoken`` is our user name: ``user``.
 224
 225 Now the parameter list is sorted:
 226
 227 ============== =====
 228 Name           Value
 229 ============== =====
 230 ``atimestamp`` ``1396353987``
 231 ``atoken``     ``user``
 232 ``bheight``    ``768``
 233 ``bwidth``     ``1024``
 234 ``sheight``    ``300``
 235 ``swidth``     ``400``
 236 ``url``        ``http://example.org/``
 237 ============== =====
 238
 239 The parameters are raw-url-encoded. The only value that changes is the url,
 240 it becomes ``http%3A%2F%2Fexample.org%2F``.
 241
 242 Concatenating the name/value pairs leads to the following string::
 243
 244     atimestamp=1396353987&atoken=user&bheight=768&bwidth=1024&sheight=300&swidth=400&url=http%3A%2F%2Fexample.org%2F
 245
 246 Creating the HMAC digest with sha1, the calculated string and our key
 247 ``secret`` gives us the following string::
 248
 249     9a12eac5ff859f9306eaaf5a18b9a931fe10b89d
 250
 251 This is the signature; it gets appended to the URL as ``asignature`` parameter.
 252
 253
 254 ============
 255 Dependencies
 256 ============
 257 - External tools:
 258
 259   - `cutycapt <http://cutycapt.sourceforge.net/>`_
 260   - `imagemagick's <http://www.imagemagick.org/>`_ ``convert``
 261   - ``xvfb-run``
 262
 263 - Libraries (already included in the ``.phar``):
 264
 265   - PEAR's ``System.php``
 266
 267
 268 =======
 269 License
 270 =======
 271 ``phancap`` is licensed under the `AGPL v3`__ or later.
 272
 273 __ http://www.gnu.org/licenses/agpl.html
 274
 275
 276 ========
 277 Homepage
 278 ========
 279 Web site
 280    http://cweiske.de/phancap.htm
 281
 282 Source code
 283    http://git.cweiske.de/phancap.git
 284
 285    Mirror: https://github.com/cweiske/phancap
 286
 287
 288 ======
 289 Author
 290 ======
 291 Written by Christian Weiske, cweiske@cweiske.de