fix "reload" button on autologin
[phorkie.git] / README.rst
1 ************************************
2 phorkie - PHP and Git based pastebin
3 ************************************
4 Self-hosted pastebin software written in PHP.
5 Pastes are editable, may have multiple files and are stored in git repositories.
6
7 Project page: http://sourceforge.net/p/phorkie/
8
9 .. contents:: Table of Contents
10
11 ========
12 Features
13 ========
14 - every paste is a git repository
15
16   - repositories can be cloned
17   - clone url can be displayed
18   - remote pastes can be forked (rel="vcs-git" and gist.github.com)
19   - single click forking of forks on different servers to your own
20 - paste editing
21
22   - add new files
23   - delete existing files
24   - replace file with upload
25 - embedding of pastes in your blog (via JavaScript or oEmbed)
26 - multiple files in one paste
27   - option to edit single files in a multi-file paste
28 - syntax highlighting with GeSHi
29 - rST and Markdown rendering
30 - image upload + display
31 - OpenID authentication
32 - external tool support
33
34   - xmllint
35   - php syntax check
36 - history in the sidebar
37
38   - old files can be downloaded easily
39 - search across pastes: description, file names and file content
40
41   - options: quoting, logical and, or, not, partial words
42 - webhook support - get notified when pastes are created, edited or deleted
43 - atom feed for new and updated pastes
44 - notifies remote instances via linkbacks when a paste has been forked
45
46
47 ============
48 Installation
49 ============
50
51 .phar
52 =====
53 Download ``phorkie-0.5.0.phar`` and put it in your web server's document root
54 directory.
55
56 No further setup needed.
57
58 .. note:: Only valid if your webserver is configured to let
59    PHP handle ``.phar`` files.
60
61    Unfortunately, no Linux distribution has this activated by default.
62
63 .. warning:: PHP has some bugs in its .phar handling code (e.g. with FPM).
64
65    So currently, the ``.phar`` option is considered experimental.
66
67
68 Zip package
69 ===========
70 1. Unzip the phorkie release file::
71
72    $ tar xjvf phorkie-0.5.0.tar.bz2
73
74 2. Create the git directories::
75
76    $ mkdir -p www/repos/git www/repos/work
77    $ chmod og+w www/repos/git www/repos/work
78
79 3. Install dependencies_
80
81 4. Copy ``data/config.php.dist`` to ``data/config.php`` and adjust it
82    to your needs::
83
84    $ cp data/config.php.dist data/config.php
85    $ $EDITOR data/config.php
86
87    Look at ``config.default.php`` for values that you may adjust.
88
89 5. Set your web server's document root to ``/path/to/phorkie/www/``
90    Alternatively, you can add a symlink to the ``www`` folder into your
91    web server's existing document root tree (being careful to keep
92    main phorkie folder outside the document root for security purposes)
93    and ensure you set the ``baseurl`` config option appropriately. You
94    must also set the ``RewriteBase`` in the ``.htaccess`` file or adjust
95    the nginx configuration accordingly.
96
97 6. Open http://yourhost/setup in your web browser to see if everything
98    is working fine.
99
100 7. Go to http://yourhost/
101
102 8. If you like phorkie, send a mail to `cweiske+phorkie@cweiske.de`__
103
104 __ mailto:cweiske+phorkie@cweiske.de
105
106
107 Dependencies
108 ============
109 phorkie stands on the shoulders of giants.
110
111 It requires the following programs to be installed
112 on your machine:
113
114 - Git v1.7.5 or later
115 - PHP v5.3.0 or later
116 - PEAR v1.9.2 or later
117
118 ::
119
120   $ pear install versioncontrol_git-alpha
121   $ pear install services_libravatar-alpha
122   $ pear install http_request2
123   $ pear install pager
124   $ pear install date_humandiff-alpha
125   $ pear install openid-alpha
126
127   $ pear channel-discover pear.twig-project.org
128   $ pear install twig/Twig
129
130   $ pear channel-discover pear.geshi.org
131   $ pear install geshi/geshi
132
133   $ pear channel-discover zustellzentrum.cweiske.de
134   $ pear install zz/mime_type_plaindetect-alpha
135
136   $ pear channel-discover pear.michelf.ca
137   $ pear install michelf/Markdown
138
139   $ pear channel-discover pear2.php.net
140   $ pear install pear2/pear2_services_linkback-alpha
141
142
143 You can use composer to install all dependencies automatically::
144
145   $ composer install
146
147 Note that the ``.phar`` package already contains all dependencies.
148
149
150 ======
151 Search
152 ======
153
154 phorkie makes use of an Elasticsearch__ installation, if you have one.
155
156 It is used to provide search capabilities and the list of recent pastes.
157
158 Elasticsearch version 1.3 is supported.
159
160 __ http://www.elasticsearch.org/
161
162
163 Setup
164 =====
165 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
166 of the index, e.g. ::
167
168   http://localhost:9200/phorkie/
169
170 You must use a search namespace with Elasticsearch such as ``phorkie/``.
171 Run the index script to import all existing pastes into the index::
172
173   php scripts/index.php
174
175 That's all. Open phorkie in your browser, and you'll notice the search box
176 in the top menu.
177
178
179 Reset
180 =====
181 In case something really went wrong and you need to reset the search
182 index, run the following command::
183
184   $ curl -XDELETE http://localhost:9200/phorkie/
185   {"ok":true,"acknowledged"}
186
187 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
188 in the configuration file.
189
190 You may also manually run the reindexing script with::
191
192   $ php scripts/index.php
193
194
195 =====
196 HowTo
197 =====
198
199 Make git repositories clonable
200 ==============================
201
202 HTTP
203 ----
204 By default, the pastes are clonable via ``http`` as long as the ``repos/git/``
205 directory is within the ``www/`` directory.
206
207 No further setup needed.
208
209
210 git-daemon
211 ----------
212 You may use ``git-daemon`` to provide public ``git://`` clone urls.
213 Install the ``git-daemon-run`` package on Debian/Ubuntu.
214
215 Make the repositories available by symlinking the paste repository
216 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
217 ``/var/cache/git``, e.g.::
218
219   $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
220
221 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
222 setting to ``git://$yourhostname/git/paste/``.
223 The rest will be appended automatically.
224
225
226 You're on your own to setup writable repositories.
227
228
229 Protect your site with OpenID
230 =============================
231 You have the option of enabling OpenID authentication to help secure your
232 pastes on phorkie.
233 Set the ``$GLOBALS['phorkie']['auth']`` values in the
234 ``data/config.php`` file as desired.
235
236 There are two different types of security you can apply.
237 First, you can restrict to one of three ``securityLevels``:
238
239 - completely open (``0``)
240 - protection of write-enabled functions such as add, edit, etc. (``1``)
241 - full site protection (``2``)
242
243 Additionally, you can restrict your site to ``listedUsersOnly``.
244 You will need to add the individual OpenID urls to the
245 ``$GLOBALS['phorkie']['auth']['users']`` variable.
246
247
248 Get information about paste editors
249 ===================================
250 Phorkie stores the user's OpenID or IP address (when not logged in) when
251 a paste is edited.
252 It is possible to get this information for each single commit::
253
254     // IP / OpenID for the latest commit
255     $ git notes --ref=identity show
256     127.0.0.1
257
258     // show IP / OpenID for a given commit
259     $ git notes --ref=identity show 29f82a
260     http://cweiske.de/
261
262
263 Notifications via webhooks
264 ==========================
265 Depending on how you use phorkie, it might be nice to notify some other service
266 when pastes are added or updated.
267 Phorkie contains a simply mechanism to post data to a given URL which
268 you can then use as needed.
269
270 The data are json-encoded POSTed to the URLs contained in the
271 ``$GLOBALS['phorkie']['cfg']['webhooks']`` setting array, with
272 a MIME type of ``application/vnd.phorkie.webhook+json``::
273
274   {
275       'event': 'create',
276       'author': {
277           'name':'Anonymous',
278           'email': 'anonymous@phorkie',
279       },
280       'repository': {
281           'name': 'webhooktest',
282           'url': 'http://example.org/33',
283           'description': 'webhooktest',
284           'owner': {
285               'name': 'Anonymous',
286               'email': 'anonymous@phorkie',
287           }
288       }
289   }
290
291 The event may be ``create``, ``edit`` or ``delete``.
292
293
294 =================
295 Technical details
296 =================
297
298
299 URLs
300 ====
301
302 ``/``
303   Index page.
304 ``/[0-9]+``
305   Display page for paste
306 ``/[0-9]+/edit``
307   Edit the paste
308 ``/[0-9]+/edit/(.+)``
309   Edit a single file of the paste
310 ``/[0-9]+/embed``
311   JavaScript code that embeds the whole paste in a HTML page
312 ``/[0-9]+/embed/(.+)``
313   JavaScript code that embeds a single file in a HTML page
314 ``/[0-9]+/raw/(.+)``
315   Display raw file contents
316 ``/[0-9]+/tool/[a-zA-Z]+/(.+)``
317   Run a tool on the given file
318 ``/[0-9]+/rev/[a-z0-9]+``
319   Show specific revision of the paste
320 ``/[0-9]+/delete``
321   Delete the paste
322 ``/[0-9]+/doap``
323   Show DOAP document for paste
324 ``/[0-9]+/fork``
325   Create a fork of the paste
326 ``/search?q=..(&page=[0-9]+)?``
327   Search for term, with optional page
328 ``/list(/[0-9]+)?``
329   List all pastes, with optional page
330 ``/fork-remote``
331   Fork a remote URL
332 ``/help``
333   Show help page
334 ``/new``
335   Shows form for new paste
336 ``/login``
337   Login page for protecting site
338 ``/setup``
339   Check if everything is setup correctly and all dependencies are installed
340 ``/user``
341   Edit logged-in user information
342
343
344 Internal directory layout
345 =========================
346 ::
347
348   repos/
349     work/
350       1/ - work directory for paste #1
351       2/ - work directory for paste #2
352     git/
353       1.git/ - git repository for paste #1
354         description - Description for the repository
355       2.git/ - git repository for paste #2
356
357 nginx rewrites
358 ==============
359 If you use nginx, place the following lines into your ``server`` block:
360
361 ::
362
363   if (!-e $request_uri) {
364     rewrite ^/([0-9]+)$ /display.php?id=$1;
365     rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
366     rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
367     rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
368     rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
369     rewrite ^/([0-9]+)/edit/(.+)$ edit.php?id=$1&file=$2
370     rewrite ^/([0-9]+)/embed$ /embed.php?id=$1;
371     rewrite ^/([0-9]+)/embed/(.+)$ embed.php?id=$1&file=$2
372     rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
373     rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
374     rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
375     rewrite ^/([0-9]+)/rev-raw/(.+)/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
376     rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
377
378     rewrite ^/fork-remote$ /fork-remote.php;
379     rewrite ^/help$ /help.php;
380     rewrite ^/new$ /new.php;
381
382     rewrite ^/feed/new$ /feed-new.php;
383     rewrite ^/feed/updated$ /feed-updated.php;
384
385     rewrite ^/list$ /list.php;
386     rewrite ^/list/([0-9]+)$ /list.php?page=$1;
387
388     rewrite ^/search$ /search.php;
389     rewrite ^/search/([0-9]+)$ /search.php?page=$1;
390
391     rewrite ^/login$ /login.php;
392     rewrite ^/setup$ /setup.php;
393     rewrite ^/user$ /user.php;
394   }
395
396 Lighttpd rewrites
397 =================
398
399 ::
400
401     url.rewrite-once += (
402         "^/([0-9]+)$" => "/display.php?id=$1",
403         "^/([0-9]+)/delete$" => "/delete.php?id=$1",
404         "^/([0-9]+)/delete/confirm" => "/delete.php?&id=$1&confirm=1",
405         "^/([0-9]+)/doap$" => "/doap.php?id=$1",
406         "^/([0-9]+)/edit$" => "/edit.php?id=$1",
407         "^/([0-9]+)/edit/(.+)" => "/edit.php?id=$1&file=$2",
408         "^/([0-9]+)/embed$" => "/embed.php?id=$1",
409         "^/([0-9]+)/embed/(.+)$" => "/embed.php?id=$1",
410         "^/([0-9]+)/fork$" => "/fork.php?id=$1",
411         "^/([0-9]+)/raw/(.+)$" => "/raw.php?id=$1&file=$2",
412         "^/([0-9]+)/rev/(.+)$" => "/revision.php?id=$1&rev=$2",
413         "^/([0-9]+)/rev-raw/(.+)/(.+)$" => "/raw.php?id=$1&rev=$2&file=$3",
414         "^/([0-9]+)/tool/([^/]+)/(.+)$" => "/tool.php?id=$1&tool=$2&file=$3",
415
416         "^/fork-remote$" => "/fork-remote.php",
417         "^/help$" => "/help.php",
418         "^/new$" => "/new.php",
419
420         "^/feed/new$" => "/feed-new.php",
421         "^/feed/updated$" => "/feed-updated.php",
422
423         "^/list$" => "/list.php",
424         "^/list/([0-9]+)$" => "/list.php?page=$1",
425
426         "^/search$" => "/search.php",
427         "^/search/([0-9]+)$" => "/search.php?page=$1",
428
429         "^/login$" => "/login.php",
430         "^/setup$" => "/setup.php",
431         "^/user$" => "/user.php"
432     )