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.
7 Project page: http://sourceforge.net/p/phorkie/
9 .. contents:: Table of Contents
14 - every paste is a git repository
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
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
36 - history in the sidebar
38 - old files can be downloaded easily
39 - search across pastes: description, file names and file content
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 - text file detection for unknown file types
54 Download ``phorkie-0.7.0.phar`` and put it in your web server's document root
57 No further setup needed.
59 .. note:: Only valid if your webserver is configured to let
60 PHP handle ``.phar`` files.
62 Unfortunately, no Linux distribution has this activated by default.
63 You can do it yourself, though - see
64 `Enable .phar handling in your web server`__.
66 .. warning:: PHP has some bugs in its .phar handling code (e.g. with FPM).
68 So currently, the ``.phar`` option is considered experimental.
70 __ http://cweiske.de/tagebuch/phar-webserver.htm
75 1. Unzip the phorkie release file::
77 $ tar xjvf phorkie-0.7.0.tar.bz2
79 2. Create the git directories::
81 $ mkdir -p www/repos/git www/repos/work
82 $ chmod og+w www/repos/git www/repos/work
84 3. Install dependencies_
86 4. Copy ``data/config.php.dist`` to ``data/config.php`` and adjust it
89 $ cp data/config.php.dist data/config.php
90 $ $EDITOR data/config.php
92 Look at ``config.default.php`` for values that you may adjust.
94 5. Set your web server's document root to ``/path/to/phorkie/www/``
95 Alternatively, you can add a symlink to the ``www`` folder into your
96 web server's existing document root tree (being careful to keep
97 main phorkie folder outside the document root for security purposes)
98 and ensure you set the ``baseurl`` config option appropriately. You
99 must also set the ``RewriteBase`` in the ``.htaccess`` file or adjust
100 the nginx configuration accordingly.
102 6. Open http://yourhost/setup in your web browser to see if everything
105 7. Go to http://yourhost/
107 8. If you like phorkie, send a mail to `cweiske+phorkie@cweiske.de`__
109 __ mailto:cweiske+phorkie@cweiske.de
114 phorkie stands on the shoulders of giants.
116 It requires the following programs to be installed
119 - Git v1.7.5 or later
120 - PHP v5.3.0 or later
122 - optionally the ``mbstring`` extension
123 - PEAR v1.9.2 or later
127 $ pear install versioncontrol_git-alpha
128 $ pear install services_libravatar-alpha
129 $ pear install http_request2
131 $ pear install date_humandiff-alpha
132 $ pear install openid-alpha
134 $ pear channel-discover pear.twig-project.org
135 $ pear install twig/Twig
137 $ pear channel-discover pear.geshi.org
138 $ pear install geshi/geshi
140 $ pear channel-discover zustellzentrum.cweiske.de
141 $ pear install zz/mime_type_plaindetect-alpha
143 $ pear channel-discover pear.michelf.ca
144 $ pear install michelf/Markdown
146 $ pear channel-discover pear2.php.net
147 $ pear install pear2/pear2_services_linkback-alpha
150 You can use composer to install all dependencies automatically::
154 Note that the ``.phar`` package already contains all dependencies.
161 phorkie makes use of an Elasticsearch__ installation, if you have one.
163 It is used to provide search capabilities and the list of recent pastes.
165 Elasticsearch version 2.0 is supported.
167 You have to install the `delete-by-query`__ plugin::
169 $ cd /usr/share/elasticsearch
170 $ bin/plugin install delete-by-query
172 __ http://www.elasticsearch.org/
173 __ https://www.elastic.co/guide/en/elasticsearch/plugins/2.0/plugins-delete-by-query.html
178 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
179 of the index, e.g. ::
181 http://localhost:9200/phorkie/
183 You must use a search namespace with Elasticsearch such as ``phorkie/``.
184 Run the index script to import all existing pastes into the index::
186 php scripts/index.php
188 That's all. Open phorkie in your browser, and you'll notice the search box
194 In case something really went wrong and you need to reset the search
195 index, run the following command::
197 $ curl -XDELETE http://localhost:9200/phorkie/
198 {"ok":true,"acknowledged"}
200 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
201 in the configuration file.
203 You may also manually run the reindexing script with::
205 $ php scripts/index.php
212 Make git repositories clonable
213 ==============================
217 By default, the pastes are clonable via ``http`` as long as the ``repos/git/``
218 directory is within the ``www/`` directory.
220 No further setup needed.
225 You may use ``git-daemon`` to provide public ``git://`` clone urls.
226 Install the ``git-daemon-run`` package on Debian/Ubuntu.
228 Make the repositories available by symlinking the paste repository
229 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
230 ``/var/cache/git``, e.g.::
232 $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
234 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
235 setting to ``git://$yourhostname/git/paste/``.
236 The rest will be appended automatically.
239 You're on your own to setup writable repositories.
242 Protect your site with OpenID
243 =============================
244 You have the option of enabling OpenID authentication to help secure your
246 Set the ``$GLOBALS['phorkie']['auth']`` values in the
247 ``data/config.php`` file as desired.
249 There are two different types of security you can apply.
250 First, you can restrict to one of three ``securityLevels``:
252 - completely open (``0``)
253 - protection of write-enabled functions such as add, edit, etc. (``1``)
254 - full site protection (``2``)
256 Additionally, you can restrict your site to ``listedUsersOnly``.
257 You will need to add the individual OpenID urls to the
258 ``$GLOBALS['phorkie']['auth']['users']`` variable.
261 Get information about paste editors
262 ===================================
263 Phorkie stores the user's OpenID or IP address (when not logged in) when
265 It is possible to get this information for each single commit::
267 // IP / OpenID for the latest commit
268 $ git notes --ref=identity show
271 // show IP / OpenID for a given commit
272 $ git notes --ref=identity show 29f82a
276 Notifications via webhooks
277 ==========================
278 Depending on how you use phorkie, it might be nice to notify some other service
279 when pastes are added or updated.
280 Phorkie contains a simply mechanism to post data to a given URL which
281 you can then use as needed.
283 The data are json-encoded POSTed to the URLs contained in the
284 ``$GLOBALS['phorkie']['cfg']['webhooks']`` setting array, with
285 a MIME type of ``application/vnd.phorkie.webhook+json``::
291 'email': 'anonymous@phorkie',
294 'name': 'webhooktest',
295 'url': 'http://example.org/33',
296 'description': 'webhooktest',
299 'email': 'anonymous@phorkie',
304 The event may be ``create``, ``edit`` or ``delete``.
318 Display page for paste
321 ``/[0-9]+/edit/(.+)``
322 Edit a single file of the paste
324 JavaScript code that embeds the whole paste in a HTML page
325 ``/[0-9]+/embed/(.+)``
326 JavaScript code that embeds a single file in a HTML page
328 Display raw file contents
329 ``/[0-9]+/tool/[a-zA-Z]+/(.+)``
330 Run a tool on the given file
331 ``/[0-9]+/rev/[a-z0-9]+``
332 Show specific revision of the paste
336 Show DOAP document for paste
338 Create a fork of the paste
339 ``/search?q=..(&page=[0-9]+)?``
340 Search for term, with optional page
342 List all pastes, with optional page
348 Shows form for new paste
350 Login page for protecting site
352 Check if everything is setup correctly and all dependencies are installed
354 Edit logged-in user information
357 Internal directory layout
358 =========================
363 1/ - work directory for paste #1
364 2/ - work directory for paste #2
366 1.git/ - git repository for paste #1
367 description - Description for the repository
368 2.git/ - git repository for paste #2
372 If you use nginx, place the following lines into your ``server`` block:
376 if (!-e $request_uri) {
377 rewrite ^/([0-9]+)$ /display.php?id=$1;
378 rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
379 rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
380 rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
381 rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
382 rewrite ^/([0-9]+)/edit/(.+)$ /edit.php?id=$1&file=$2;
383 rewrite ^/([0-9]+)/embed$ /embed.php?id=$1;
384 rewrite ^/([0-9]+)/embed/(.+)$ /embed.php?id=$1&file=$2;
385 rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
386 rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
387 rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
388 rewrite ^/([0-9]+)/rev-raw/(.+)/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
389 rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
391 rewrite ^/fork-remote$ /fork-remote.php;
392 rewrite ^/help$ /help.php;
393 rewrite ^/new$ /new.php;
395 rewrite ^/feed/new$ /feed-new.php;
396 rewrite ^/feed/updated$ /feed-updated.php;
398 rewrite ^/list$ /list.php;
399 rewrite ^/list/([0-9]+)$ /list.php?page=$1;
401 rewrite ^/search$ /search.php;
402 rewrite ^/search/([0-9]+)$ /search.php?page=$1;
404 rewrite ^/login$ /login.php;
405 rewrite ^/setup$ /setup.php;
406 rewrite ^/user$ /user.php;
414 url.rewrite-once += (
415 "^/([0-9]+)$" => "/display.php?id=$1",
416 "^/([0-9]+)/delete$" => "/delete.php?id=$1",
417 "^/([0-9]+)/delete/confirm" => "/delete.php?&id=$1&confirm=1",
418 "^/([0-9]+)/doap$" => "/doap.php?id=$1",
419 "^/([0-9]+)/edit$" => "/edit.php?id=$1",
420 "^/([0-9]+)/edit/(.+)" => "/edit.php?id=$1&file=$2",
421 "^/([0-9]+)/embed$" => "/embed.php?id=$1",
422 "^/([0-9]+)/embed/(.+)$" => "/embed.php?id=$1",
423 "^/([0-9]+)/fork$" => "/fork.php?id=$1",
424 "^/([0-9]+)/raw/(.+)$" => "/raw.php?id=$1&file=$2",
425 "^/([0-9]+)/rev/(.+)$" => "/revision.php?id=$1&rev=$2",
426 "^/([0-9]+)/rev-raw/(.+)/(.+)$" => "/raw.php?id=$1&rev=$2&file=$3",
427 "^/([0-9]+)/tool/([^/]+)/(.+)$" => "/tool.php?id=$1&tool=$2&file=$3",
429 "^/fork-remote$" => "/fork-remote.php",
430 "^/help$" => "/help.php",
431 "^/new$" => "/new.php",
433 "^/feed/new$" => "/feed-new.php",
434 "^/feed/updated$" => "/feed-updated.php",
436 "^/list$" => "/list.php",
437 "^/list/([0-9]+)$" => "/list.php?page=$1",
439 "^/search$" => "/search.php",
440 "^/search/([0-9]+)$" => "/search.php?page=$1",
442 "^/login$" => "/login.php",
443 "^/setup$" => "/setup.php",
444 "^/user$" => "/user.php"
452 Releasing a new version
453 =======================
455 #. Update ``ChangeLog``, ``NEWS.rst``, ``build.xml`` and ``README.rst``.
456 #. Update local dependencies::
459 #. Build ``.tar.bz2`` and ``.phar`` release files with::
464 #. Tag the release in git
465 #. Upload release to sourceforge::