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 v8.0.0 or later
138 - with the ``mbstring`` extension
139 - A dozen of libraries
141 Use composer to install all dependencies::
143 $ composer install --no-dev
145 Note that the ``.phar`` package already contains all dependencies.
152 phorkie makes use of an Elasticsearch__ installation, if you have one.
154 It is used to provide search capabilities and the list of recent pastes.
156 Elasticsearch version 2.0 is supported.
158 You have to install the `delete-by-query`__ plugin::
160 $ cd /usr/share/elasticsearch
161 $ bin/plugin install delete-by-query
163 __ http://www.elasticsearch.org/
164 __ https://www.elastic.co/guide/en/elasticsearch/plugins/2.0/plugins-delete-by-query.html
169 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
170 of the index, e.g. ::
172 http://localhost:9200/phorkie/
174 You must use a search namespace with Elasticsearch such as ``phorkie/``.
175 Run the index script to import all existing pastes into the index::
177 php scripts/index.php
179 That's all. Open phorkie in your browser, and you'll notice the search box
185 In case something really went wrong and you need to reset the search
186 index, run the following command::
188 $ curl -XDELETE http://localhost:9200/phorkie/
189 {"ok":true,"acknowledged"}
191 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
192 in the configuration file.
194 You may also manually run the reindexing script with::
196 $ php scripts/index.php
203 Make git repositories clonable
204 ==============================
208 By default, the pastes are clonable via ``http`` as long as the ``repos/git/``
209 directory is within the ``www/`` directory.
211 No further setup needed.
216 You may use ``git-daemon`` to provide public ``git://`` clone urls.
217 Install the ``git-daemon-run`` package on Debian/Ubuntu.
219 Make the repositories available by symlinking the paste repository
220 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
221 ``/var/cache/git``, e.g.::
223 $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
225 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
226 setting to ``git://$yourhostname/git/paste/``.
227 The rest will be appended automatically.
230 You're on your own to setup writable repositories.
233 Protect your site with OpenID
234 =============================
235 You have the option of enabling OpenID authentication to help secure your
237 Set the ``$GLOBALS['phorkie']['auth']`` values in the
238 ``data/config.php`` file as desired.
240 There are two different types of security you can apply.
241 First, you can restrict to one of three ``securityLevels``:
243 - completely open (``0``)
244 - protection of write-enabled functions such as add, edit, etc. (``1``)
245 - full site protection (``2``)
247 Additionally, you can restrict your site to ``listedUsersOnly``.
248 You will need to add the individual OpenID urls to the
249 ``$GLOBALS['phorkie']['auth']['users']`` variable.
252 Get information about paste editors
253 ===================================
254 Phorkie stores the user's OpenID or IP address (when not logged in) when
256 It is possible to get this information for each single commit::
258 // IP / OpenID for the latest commit
259 $ git notes --ref=identity show
262 // show IP / OpenID for a given commit
263 $ git notes --ref=identity show 29f82a
267 Notifications via webhooks
268 ==========================
269 Depending on how you use phorkie, it might be nice to notify some other service
270 when pastes are added or updated.
271 Phorkie contains a simply mechanism to post data to a given URL which
272 you can then use as needed.
274 The data are json-encoded POSTed to the URLs contained in the
275 ``$GLOBALS['phorkie']['cfg']['webhooks']`` setting array, with
276 a MIME type of ``application/vnd.phorkie.webhook+json``::
282 'email': 'anonymous@phorkie',
285 'name': 'webhooktest',
286 'url': 'http://example.org/33',
287 'description': 'webhooktest',
290 'email': 'anonymous@phorkie',
295 The event may be ``create``, ``edit`` or ``delete``.
309 Display page for paste
312 ``/[0-9]+/edit/(.+)``
313 Edit a single file of the paste
315 JavaScript code that embeds the whole paste in a HTML page
316 ``/[0-9]+/embed/(.+)``
317 JavaScript code that embeds a single file in a HTML page
319 Display raw file contents
320 ``/[0-9]+/tool/[a-zA-Z]+/(.+)``
321 Run a tool on the given file
322 ``/[0-9]+/rev/[a-z0-9]+``
323 Show specific revision of the paste
327 Show DOAP document for paste
329 Create a fork of the paste
330 ``/search?q=..(&page=[0-9]+)?``
331 Search for term, with optional page
333 List all pastes, with optional page
339 Shows form for new paste
341 Login page for protecting site
343 Check if everything is setup correctly and all dependencies are installed
345 Edit logged-in user information
348 Internal directory layout
349 =========================
354 1/ - work directory for paste #1
355 2/ - work directory for paste #2
357 1.git/ - git repository for paste #1
358 description - Description for the repository
359 2.git/ - git repository for paste #2
363 If you use nginx, place the following lines into your ``server`` block:
367 if (!-e $request_uri) {
368 rewrite ^/([0-9]+)$ /display.php?id=$1;
369 rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
370 rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
371 rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
372 rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
373 rewrite ^/([0-9]+)/edit/(.+)$ /edit.php?id=$1&file=$2;
374 rewrite ^/([0-9]+)/embed$ /embed.php?id=$1;
375 rewrite ^/([0-9]+)/embed/(.+)$ /embed.php?id=$1&file=$2;
376 rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
377 rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
378 rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
379 rewrite ^/([0-9]+)/rev-raw/(.+)/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
380 rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
382 rewrite ^/fork-remote$ /fork-remote.php;
383 rewrite ^/help$ /help.php;
384 rewrite ^/new$ /new.php;
386 rewrite ^/feed/new$ /feed-new.php;
387 rewrite ^/feed/updated$ /feed-updated.php;
389 rewrite ^/list$ /list.php;
390 rewrite ^/list/([0-9]+)$ /list.php?page=$1;
392 rewrite ^/search$ /search.php;
393 rewrite ^/search/([0-9]+)$ /search.php?page=$1;
395 rewrite ^/login$ /login.php;
396 rewrite ^/setup$ /setup.php;
397 rewrite ^/user$ /user.php;
405 url.rewrite-once += (
406 "^/([0-9]+)$" => "/display.php?id=$1",
407 "^/([0-9]+)/delete$" => "/delete.php?id=$1",
408 "^/([0-9]+)/delete/confirm" => "/delete.php?&id=$1&confirm=1",
409 "^/([0-9]+)/doap$" => "/doap.php?id=$1",
410 "^/([0-9]+)/edit$" => "/edit.php?id=$1",
411 "^/([0-9]+)/edit/(.+)" => "/edit.php?id=$1&file=$2",
412 "^/([0-9]+)/embed$" => "/embed.php?id=$1",
413 "^/([0-9]+)/embed/(.+)$" => "/embed.php?id=$1",
414 "^/([0-9]+)/fork$" => "/fork.php?id=$1",
415 "^/([0-9]+)/raw/(.+)$" => "/raw.php?id=$1&file=$2",
416 "^/([0-9]+)/rev/(.+)$" => "/revision.php?id=$1&rev=$2",
417 "^/([0-9]+)/rev-raw/(.+)/(.+)$" => "/raw.php?id=$1&rev=$2&file=$3",
418 "^/([0-9]+)/tool/([^/]+)/(.+)$" => "/tool.php?id=$1&tool=$2&file=$3",
420 "^/fork-remote$" => "/fork-remote.php",
421 "^/help$" => "/help.php",
422 "^/new$" => "/new.php",
424 "^/feed/new$" => "/feed-new.php",
425 "^/feed/updated$" => "/feed-updated.php",
427 "^/list$" => "/list.php",
428 "^/list/([0-9]+)$" => "/list.php?page=$1",
430 "^/search$" => "/search.php",
431 "^/search/([0-9]+)$" => "/search.php?page=$1",
433 "^/login$" => "/login.php",
434 "^/setup$" => "/setup.php",
435 "^/user$" => "/user.php"
443 Releasing a new version
444 =======================
446 #. Update ``ChangeLog``, ``NEWS.rst``, ``build.xml`` and ``README.rst``.
447 #. Update local dependencies::
450 #. Build ``.tar.bz2`` and ``.phar`` release files with::
455 #. Tag the release in git
456 #. Run the script to update the homepage
458 $ cd /home/cweiske/Dev/html/cweiske.de
459 $ ./scripts/update-phorkie.sh