prepare release of 0.5.0
[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
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
103 Dependencies
104 ============
105 phorkie stands on the shoulders of giants.
106
107 It requires the following programs to be installed
108 on your machine:
109
110 - Git v1.7.5 or later
111 - PHP v5.3.0 or later
112 - PEAR v1.9.2 or later
113
114 ::
115
116   $ pear install versioncontrol_git-alpha
117   $ pear install services_libravatar-alpha
118   $ pear install http_request2
119   $ pear install pager
120   $ pear install date_humandiff-alpha
121   $ pear install openid-alpha
122
123   $ pear channel-discover pear.twig-project.org
124   $ pear install twig/Twig
125
126   $ pear channel-discover pear.geshi.org
127   $ pear install geshi/geshi
128
129   $ pear channel-discover zustellzentrum.cweiske.de
130   $ pear install zz/mime_type_plaindetect-alpha
131
132   $ pear channel-discover pear.michelf.ca
133   $ pear install michelf/Markdown
134
135   $ pear channel-discover pear2.php.net
136   $ pear install pear2/pear2_services_linkback-alpha
137
138
139 You can use composer to install all dependencies automatically::
140
141   $ composer install
142
143 Note that the ``.phar`` package already contains all dependencies.
144
145
146 ======
147 Search
148 ======
149
150 phorkie makes use of an Elasticsearch__ installation, if you have one.
151
152 It is used to provide search capabilities and the list of recent pastes.
153
154 Elasticsearch version 1.3 is supported.
155
156 __ http://www.elasticsearch.org/
157
158
159 Setup
160 =====
161 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
162 of the index, e.g. ::
163
164   http://localhost:9200/phorkie/
165
166 You must use a search namespace with Elasticsearch such as ``phorkie/``.
167 Run the index script to import all existing pastes into the index::
168
169   php scripts/index.php
170
171 That's all. Open phorkie in your browser, and you'll notice the search box
172 in the top menu.
173
174
175 Reset
176 =====
177 In case something really went wrong and you need to reset the search
178 index, run the following command::
179
180   $ curl -XDELETE http://localhost:9200/phorkie/
181   {"ok":true,"acknowledged"}
182
183 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
184 in the configuration file.
185
186 You may also manually run the reindexing script with::
187
188   $ php scripts/index.php
189
190
191 =====
192 HowTo
193 =====
194
195 Make git repositories clonable
196 ==============================
197
198 HTTP
199 ----
200 By default, the pastes are clonable via ``http`` as long as the ``repos/git/``
201 directory is within the ``www/`` directory.
202
203 No further setup needed.
204
205
206 git-daemon
207 ----------
208 You may use ``git-daemon`` to provide public ``git://`` clone urls.
209 Install the ``git-daemon-run`` package on Debian/Ubuntu.
210
211 Make the repositories available by symlinking the paste repository
212 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
213 ``/var/cache/git``, e.g.::
214
215   $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
216
217 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
218 setting to ``git://$yourhostname/git/paste/``.
219 The rest will be appended automatically.
220
221
222 You're on your own to setup writable repositories.
223
224
225 Protect your site with OpenID
226 =============================
227 You have the option of enabling OpenID authentication to help secure your
228 pastes on phorkie.
229 Set the ``$GLOBALS['phorkie']['auth']`` values in the
230 ``data/config.php`` file as desired.
231
232 There are two different types of security you can apply.
233 First, you can restrict to one of three ``securityLevels``:
234
235 - completely open (``0``)
236 - protection of write-enabled functions such as add, edit, etc. (``1``)
237 - full site protection (``2``)
238
239 Additionally, you can restrict your site to ``listedUsersOnly``.
240 You will need to add the individual OpenID urls to the
241 ``$GLOBALS['phorkie']['auth']['users']`` variable.
242
243
244 Get information about paste editors
245 ===================================
246 Phorkie stores the user's OpenID or IP address (when not logged in) when
247 a paste is edited.
248 It is possible to get this information for each single commit::
249
250     // IP / OpenID for the latest commit
251     $ git notes --ref=identity show
252     127.0.0.1
253
254     // show IP / OpenID for a given commit
255     $ git notes --ref=identity show 29f82a
256     http://cweiske.de/
257
258
259 Notifications via webhooks
260 ==========================
261 Depending on how you use phorkie, it might be nice to notify some other service
262 when pastes are added or updated.
263 Phorkie contains a simply mechanism to post data to a given URL which
264 you can then use as needed.
265
266 The data are json-encoded POSTed to the URLs contained in the
267 ``$GLOBALS['phorkie']['cfg']['webhooks']`` setting array, with
268 a MIME type of ``application/vnd.phorkie.webhook+json``::
269
270   {
271       'event': 'create',
272       'author': {
273           'name':'Anonymous',
274           'email': 'anonymous@phorkie',
275       },
276       'repository': {
277           'name': 'webhooktest',
278           'url': 'http://example.org/33',
279           'description': 'webhooktest',
280           'owner': {
281               'name': 'Anonymous',
282               'email': 'anonymous@phorkie',
283           }
284       }
285   }
286
287 The event may be ``create``, ``edit`` or ``delete``.
288
289
290 =================
291 Technical details
292 =================
293
294
295 URLs
296 ====
297
298 ``/``
299   Index page.
300 ``/[0-9]+``
301   Display page for paste
302 ``/[0-9]+/edit``
303   Edit the paste
304 ``/[0-9]+/edit/(.+)``
305   Edit a single file of the paste
306 ``/[0-9]+/embed``
307   JavaScript code that embeds the whole paste in a HTML page
308 ``/[0-9]+/embed/(.+)``
309   JavaScript code that embeds a single file in a HTML page
310 ``/[0-9]+/raw/(.+)``
311   Display raw file contents
312 ``/[0-9]+/tool/[a-zA-Z]+/(.+)``
313   Run a tool on the given file
314 ``/[0-9]+/rev/[a-z0-9]+``
315   Show specific revision of the paste
316 ``/[0-9]+/delete``
317   Delete the paste
318 ``/[0-9]+/doap``
319   Show DOAP document for paste
320 ``/[0-9]+/fork``
321   Create a fork of the paste
322 ``/search?q=..(&page=[0-9]+)?``
323   Search for term, with optional page
324 ``/list(/[0-9]+)?``
325   List all pastes, with optional page
326 ``/fork-remote``
327   Fork a remote URL
328 ``/help``
329   Show help page
330 ``/new``
331   Shows form for new paste
332 ``/login``
333   Login page for protecting site
334 ``/setup``
335   Check if everything is setup correctly and all dependencies are installed
336 ``/user``
337   Edit logged-in user information
338
339
340 Internal directory layout
341 =========================
342 ::
343
344   repos/
345     work/
346       1/ - work directory for paste #1
347       2/ - work directory for paste #2
348     git/
349       1.git/ - git repository for paste #1
350         description - Description for the repository
351       2.git/ - git repository for paste #2
352
353 nginx rewrites
354 ==============
355 If you use nginx, place the following lines into your ``server`` block:
356
357 ::
358
359   if (!-e $request_uri) {
360     rewrite ^/([0-9]+)$ /display.php?id=$1;
361     rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
362     rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
363     rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
364     rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
365     rewrite ^/([0-9]+)/edit/(.+)$ edit.php?id=$1&file=$2
366     rewrite ^/([0-9]+)/embed$ /embed.php?id=$1;
367     rewrite ^/([0-9]+)/embed/(.+)$ embed.php?id=$1&file=$2
368     rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
369     rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
370     rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
371     rewrite ^/([0-9]+)/rev-raw/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
372     rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
373
374     rewrite ^/fork-remote$ /fork-remote.php;
375     rewrite ^/help$ /help.php;
376     rewrite ^/new$ /new.php;
377
378     rewrite ^/feed/new$ /feed-new.php;
379     rewrite ^/feed/updated$ /feed-updated.php;
380
381     rewrite ^/list$ /list.php;
382     rewrite ^/list/([0-9]+)$ /list.php?page=$1;
383
384     rewrite ^/search$ /search.php;
385     rewrite ^/search/([0-9]+)$ /search.php?page=$1;
386
387     rewrite ^/login$ /login.php;
388     rewrite ^/setup$ /setup.php;
389     rewrite ^/user$ /user.php;
390   }