1 ****************************
2 phorkie - 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 `Homepage <https://cweiske.de/phorkie.htm>`__
8 | `Bug tracker <https://github.com/cweiske/phorkie/issues>`__
9 | `Git repository <https://git.cweiske.de/phorkie.git>`__
10 ยท `GitHub mirror <https://github.com/cweiske/phorkie/>`__
11 | `News <https://cweiske.de/phorkie-news.htm>`__
13 .. contents:: Table of Contents
18 - every paste is a git repository
20 - repositories can be cloned
21 - clone url can be displayed
22 - remote pastes can be forked (rel="vcs-git" and gist.github.com)
23 - single click forking of forks on different servers to your own
27 - delete existing files
28 - replace file with upload
29 - embedding of pastes in your blog (via JavaScript or oEmbed)
30 - multiple files in one paste
31 - option to edit single files in a multi-file paste
32 - syntax highlighting with GeSHi
33 - rST and Markdown rendering
34 - image upload + display
35 - OpenID authentication
36 - external tool support
40 - history in the sidebar
42 - old files can be downloaded easily
43 - search across pastes: description, file names and file content
45 - options: quoting, logical and, or, not, partial words
46 - webhook support - get notified when pastes are created, edited or deleted
47 - atom feed for new and updated pastes
48 - notifies remote instances via linkbacks when a paste has been forked
49 - text file detection for unknown file types
55 phorkie is released as self-contained ``.phar`` file that includes
56 all dependencies, as well as a normal zip file.
60 See `phorkie downloads page <http://cweiske.de/phorkie-download.htm>`_
61 for all released versions.
70 Download ``phorkie-0.8.1.phar`` and put it in your web server's document root
73 No further setup needed.
75 .. note:: Only valid if your webserver is configured to let
76 PHP handle ``.phar`` files.
78 Unfortunately, no Linux distribution has this activated by default.
79 You can do it yourself, though - see
80 `Enable .phar handling in your web server`__.
82 .. warning:: PHP has some bugs in its .phar handling code (e.g. with FPM).
84 So currently, the ``.phar`` option is considered experimental.
86 __ http://cweiske.de/tagebuch/phar-webserver.htm
91 1. Unzip the phorkie release file::
93 $ tar xjvf phorkie-0.8.1.tar.bz2
95 2. Create the git directories::
97 $ mkdir -p www/repos/git www/repos/work
98 $ chmod og+w www/repos/git www/repos/work
100 3. Install dependencies_
102 4. Copy ``data/config.php.dist`` to ``data/config.php`` and adjust it
105 $ cp data/config.php.dist data/config.php
106 $ $EDITOR data/config.php
108 Look at ``config.default.php`` for values that you may adjust.
110 5. Set your web server's document root to ``/path/to/phorkie/www/``
111 Alternatively, you can add a symlink to the ``www`` folder into your
112 web server's existing document root tree (being careful to keep
113 main phorkie folder outside the document root for security purposes)
114 and ensure you set the ``baseurl`` config option appropriately. You
115 must also set the ``RewriteBase`` in the ``.htaccess`` file or adjust
116 the nginx configuration accordingly.
118 6. Open http://yourhost/setup in your web browser to see if everything
121 7. Go to http://yourhost/
123 8. If you like phorkie, send a mail to `cweiske+phorkie@cweiske.de`__
125 __ mailto:cweiske+phorkie@cweiske.de
130 phorkie stands on the shoulders of giants.
132 It requires the following programs to be installed
135 - Git v1.7.5 or later
136 - PHP v5.3.0 or later
138 - optionally the ``mbstring`` extension
139 - PEAR v1.9.2 or later
143 $ pear install versioncontrol_git-alpha
144 $ pear install services_libravatar-alpha
145 $ pear install http_request2
147 $ pear install date_humandiff-alpha
148 $ pear install openid-alpha
150 $ pear channel-discover pear.twig-project.org
151 $ pear install twig/Twig
153 $ pear channel-discover pear.geshi.org
154 $ pear install geshi/geshi
156 $ pear channel-discover zustellzentrum.cweiske.de
157 $ pear install zz/mime_type_plaindetect-alpha
159 $ pear channel-discover pear.michelf.ca
160 $ pear install michelf/Markdown
162 $ pear channel-discover pear2.php.net
163 $ pear install pear2/pear2_services_linkback-alpha
166 You can use composer to install all dependencies automatically::
170 Note that the ``.phar`` package already contains all dependencies.
177 phorkie makes use of an Elasticsearch__ installation, if you have one.
179 It is used to provide search capabilities and the list of recent pastes.
181 Elasticsearch version 2.0 is supported.
183 You have to install the `delete-by-query`__ plugin::
185 $ cd /usr/share/elasticsearch
186 $ bin/plugin install delete-by-query
188 __ http://www.elasticsearch.org/
189 __ https://www.elastic.co/guide/en/elasticsearch/plugins/2.0/plugins-delete-by-query.html
194 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
195 of the index, e.g. ::
197 http://localhost:9200/phorkie/
199 You must use a search namespace with Elasticsearch such as ``phorkie/``.
200 Run the index script to import all existing pastes into the index::
202 php scripts/index.php
204 That's all. Open phorkie in your browser, and you'll notice the search box
210 In case something really went wrong and you need to reset the search
211 index, run the following command::
213 $ curl -XDELETE http://localhost:9200/phorkie/
214 {"ok":true,"acknowledged"}
216 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
217 in the configuration file.
219 You may also manually run the reindexing script with::
221 $ php scripts/index.php
228 Make git repositories clonable
229 ==============================
233 By default, the pastes are clonable via ``http`` as long as the ``repos/git/``
234 directory is within the ``www/`` directory.
236 No further setup needed.
241 You may use ``git-daemon`` to provide public ``git://`` clone urls.
242 Install the ``git-daemon-run`` package on Debian/Ubuntu.
244 Make the repositories available by symlinking the paste repository
245 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
246 ``/var/cache/git``, e.g.::
248 $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
250 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
251 setting to ``git://$yourhostname/git/paste/``.
252 The rest will be appended automatically.
255 You're on your own to setup writable repositories.
258 Protect your site with OpenID
259 =============================
260 You have the option of enabling OpenID authentication to help secure your
262 Set the ``$GLOBALS['phorkie']['auth']`` values in the
263 ``data/config.php`` file as desired.
265 There are two different types of security you can apply.
266 First, you can restrict to one of three ``securityLevels``:
268 - completely open (``0``)
269 - protection of write-enabled functions such as add, edit, etc. (``1``)
270 - full site protection (``2``)
272 Additionally, you can restrict your site to ``listedUsersOnly``.
273 You will need to add the individual OpenID urls to the
274 ``$GLOBALS['phorkie']['auth']['users']`` variable.
277 Get information about paste editors
278 ===================================
279 Phorkie stores the user's OpenID or IP address (when not logged in) when
281 It is possible to get this information for each single commit::
283 // IP / OpenID for the latest commit
284 $ git notes --ref=identity show
287 // show IP / OpenID for a given commit
288 $ git notes --ref=identity show 29f82a
292 Notifications via webhooks
293 ==========================
294 Depending on how you use phorkie, it might be nice to notify some other service
295 when pastes are added or updated.
296 Phorkie contains a simply mechanism to post data to a given URL which
297 you can then use as needed.
299 The data are json-encoded POSTed to the URLs contained in the
300 ``$GLOBALS['phorkie']['cfg']['webhooks']`` setting array, with
301 a MIME type of ``application/vnd.phorkie.webhook+json``::
307 'email': 'anonymous@phorkie',
310 'name': 'webhooktest',
311 'url': 'http://example.org/33',
312 'description': 'webhooktest',
315 'email': 'anonymous@phorkie',
320 The event may be ``create``, ``edit`` or ``delete``.
334 Display page for paste
337 ``/[0-9]+/edit/(.+)``
338 Edit a single file of the paste
340 JavaScript code that embeds the whole paste in a HTML page
341 ``/[0-9]+/embed/(.+)``
342 JavaScript code that embeds a single file in a HTML page
344 Display raw file contents
345 ``/[0-9]+/tool/[a-zA-Z]+/(.+)``
346 Run a tool on the given file
347 ``/[0-9]+/rev/[a-z0-9]+``
348 Show specific revision of the paste
352 Show DOAP document for paste
354 Create a fork of the paste
355 ``/search?q=..(&page=[0-9]+)?``
356 Search for term, with optional page
358 List all pastes, with optional page
364 Shows form for new paste
366 Login page for protecting site
368 Check if everything is setup correctly and all dependencies are installed
370 Edit logged-in user information
373 Internal directory layout
374 =========================
379 1/ - work directory for paste #1
380 2/ - work directory for paste #2
382 1.git/ - git repository for paste #1
383 description - Description for the repository
384 2.git/ - git repository for paste #2
388 If you use nginx, place the following lines into your ``server`` block:
392 if (!-e $request_uri) {
393 rewrite ^/([0-9]+)$ /display.php?id=$1;
394 rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
395 rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
396 rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
397 rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
398 rewrite ^/([0-9]+)/edit/(.+)$ /edit.php?id=$1&file=$2;
399 rewrite ^/([0-9]+)/embed$ /embed.php?id=$1;
400 rewrite ^/([0-9]+)/embed/(.+)$ /embed.php?id=$1&file=$2;
401 rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
402 rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
403 rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
404 rewrite ^/([0-9]+)/rev-raw/(.+)/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
405 rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
407 rewrite ^/fork-remote$ /fork-remote.php;
408 rewrite ^/help$ /help.php;
409 rewrite ^/new$ /new.php;
411 rewrite ^/feed/new$ /feed-new.php;
412 rewrite ^/feed/updated$ /feed-updated.php;
414 rewrite ^/list$ /list.php;
415 rewrite ^/list/([0-9]+)$ /list.php?page=$1;
417 rewrite ^/search$ /search.php;
418 rewrite ^/search/([0-9]+)$ /search.php?page=$1;
420 rewrite ^/login$ /login.php;
421 rewrite ^/setup$ /setup.php;
422 rewrite ^/user$ /user.php;
430 url.rewrite-once += (
431 "^/([0-9]+)$" => "/display.php?id=$1",
432 "^/([0-9]+)/delete$" => "/delete.php?id=$1",
433 "^/([0-9]+)/delete/confirm" => "/delete.php?&id=$1&confirm=1",
434 "^/([0-9]+)/doap$" => "/doap.php?id=$1",
435 "^/([0-9]+)/edit$" => "/edit.php?id=$1",
436 "^/([0-9]+)/edit/(.+)" => "/edit.php?id=$1&file=$2",
437 "^/([0-9]+)/embed$" => "/embed.php?id=$1",
438 "^/([0-9]+)/embed/(.+)$" => "/embed.php?id=$1",
439 "^/([0-9]+)/fork$" => "/fork.php?id=$1",
440 "^/([0-9]+)/raw/(.+)$" => "/raw.php?id=$1&file=$2",
441 "^/([0-9]+)/rev/(.+)$" => "/revision.php?id=$1&rev=$2",
442 "^/([0-9]+)/rev-raw/(.+)/(.+)$" => "/raw.php?id=$1&rev=$2&file=$3",
443 "^/([0-9]+)/tool/([^/]+)/(.+)$" => "/tool.php?id=$1&tool=$2&file=$3",
445 "^/fork-remote$" => "/fork-remote.php",
446 "^/help$" => "/help.php",
447 "^/new$" => "/new.php",
449 "^/feed/new$" => "/feed-new.php",
450 "^/feed/updated$" => "/feed-updated.php",
452 "^/list$" => "/list.php",
453 "^/list/([0-9]+)$" => "/list.php?page=$1",
455 "^/search$" => "/search.php",
456 "^/search/([0-9]+)$" => "/search.php?page=$1",
458 "^/login$" => "/login.php",
459 "^/setup$" => "/setup.php",
460 "^/user$" => "/user.php"
468 Releasing a new version
469 =======================
471 #. Update ``ChangeLog``, ``NEWS.rst``, ``build.xml`` and ``README.rst``.
472 #. Update local dependencies::
475 #. Build ``.tar.bz2`` and ``.phar`` release files with::
480 #. Tag the release in git
481 #. Run the script to update the homepage
483 $ cd /home/cweiske/Dev/html/cweiske.de
484 $ ./scripts/update-phorkie.sh