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