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 - multiple files in one paste
26 - option to edit single files in a multi-file paste
27 - syntax highlighting with GeSHi
28 - rST and Markdown rendering
29 - image upload + display
30 - OpenID authentication
31 - external tool support
35 - history in the sidebar
37 - old files can be downloaded easily
38 - search across pastes: description, file names and file content
40 - options: quoting, logical and, or, not, partial words
41 - webhook support - get notified when pastes are created, edited or deleted
42 - atom feed for new and updated pastes
43 - notifies remote instances via linkbacks when a paste has been forked
52 Download ``phorkie-0.4.0.phar`` and put it in your web server's document root
55 No further setup needed.
57 .. note:: Only valid if your webserver is configured to let
58 PHP handle ``.phar`` files.
60 Unfortunately, no Linux distribution has this activated by default.
62 .. warning:: PHP has some bugs in its .phar handling code (e.g. with FPM).
64 So currently, the ``.phar`` option is considered experimental.
69 1. Unzip the phorkie release file::
71 $ tar xjvf phorkie-0.4.0.tar.bz2
73 2. Create the git directories::
75 $ mkdir -p www/repos/git www/repos/work
76 $ chmod og+w www/repos/git www/repos/work
78 3. Install dependencies_
80 4. Copy ``data/config.php.dist`` to ``data/config.php`` and adjust it
83 $ cp data/config.php.dist data/config.php
84 $ $EDITOR data/config.php
86 Look at ``config.default.php`` for values that you may adjust.
88 5. Set your web server's document root to ``/path/to/phorkie/www/``
89 Alternatively, you can add a symlink to the ``www`` folder into your
90 web server's existing document root tree (being careful to keep
91 main phorkie folder outside the document root for security purposes)
92 and ensure you set the ``baseurl`` config option appropriately. You
93 must also set the ``RewriteBase`` in the ``.htaccess`` file or adjust
94 the nginx configuration accordingly.
96 6. Open http://yourhost/setup in your web browser to see if everything
99 7. Go to http://yourhost/
104 phorkie stands on the shoulders of giants.
106 It requires the following programs to be installed
109 - Git v1.7.5 or later
110 - PHP v5.3.0 or later
111 - PEAR v1.9.2 or later
115 $ pear install versioncontrol_git-alpha
116 $ pear install services_libravatar-alpha
117 $ pear install http_request2
119 $ pear install date_humandiff-alpha
120 $ pear install openid-alpha
122 $ pear channel-discover pear.twig-project.org
123 $ pear install twig/Twig
125 $ pear channel-discover pear.geshi.org
126 $ pear install geshi/geshi
128 $ pear channel-discover zustellzentrum.cweiske.de
129 $ pear install zz/mime_type_plaindetect-alpha
131 $ pear channel-discover pear.michelf.ca
132 $ pear install michelf/Markdown
134 $ pear channel-discover pear2.php.net
135 $ pear install pear2/pear2_services_linkback-alpha
138 You can use composer to install all dependencies automatically::
142 Note that the ``.phar`` package already contains all dependencies.
149 phorkie makes use of an Elasticsearch__ installation, if you have one.
151 It is used to provide search capabilities and the list of recent pastes.
153 __ http://www.elasticsearch.org/
158 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
159 of the index, e.g. ::
161 http://localhost:9200/phorkie/
163 You must use a search namespace with Elasticsearch such as ``phorkie/``.
164 Run the index script to import all existing pastes into the index::
166 php scripts/index.php
168 That's all. Open phorkie in your browser, and you'll notice the search box
174 In case something really went wrong and you need to reset the search
175 index, run the following command::
177 $ curl -XDELETE http://localhost:9200/phorkie/
178 {"ok":true,"acknowledged"}
180 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
181 in the configuration file.
183 You may also manually run the reindexing script with::
185 $ php scripts/index.php
192 Make git repositories clonable
193 ==============================
197 By default, the pastes are clonable via ``http`` as long as the ``repos/git/``
198 directory is within the ``www/`` directory.
200 No further setup needed.
205 You may use ``git-daemon`` to provide public ``git://`` clone urls.
206 Install the ``git-daemon-run`` package on Debian/Ubuntu.
208 Make the repositories available by symlinking the paste repository
209 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
210 ``/var/cache/git``, e.g.::
212 $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
214 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
215 setting to ``git://$yourhostname/git/paste/``.
216 The rest will be appended automatically.
219 You're on your own to setup writable repositories.
222 Protect your site with OpenID
223 =============================
224 You have the option of enabling OpenID authentication to help secure your
226 Set the ``$GLOBALS['phorkie']['auth']`` values in the
227 ``data/config.php`` file as desired.
229 There are two different types of security you can apply.
230 First, you can restrict to one of three ``securityLevels``:
232 - completely open (``0``)
233 - protection of write-enabled functions such as add, edit, etc. (``1``)
234 - full site protection (``2``)
236 Additionally, you can restrict your site to ``listedUsersOnly``.
237 You will need to add the individual OpenID urls to the
238 ``$GLOBALS['phorkie']['auth']['users']`` variable.
241 Get information about paste editors
242 ===================================
243 Phorkie stores the user's OpenID or IP address (when not logged in) when
245 It is possible to get this information for each single commit::
247 // IP / OpenID for the latest commit
248 $ git notes --ref=identity show
251 // show IP / OpenID for a given commit
252 $ git notes --ref=identity show 29f82a
256 Notifications via webhooks
257 ==========================
258 Depending on how you use phorkie, it might be nice to notify some other service
259 when pastes are added or updated.
260 Phorkie contains a simply mechanism to post data to a given URL which
261 you can then use as needed.
263 The data are json-encoded POSTed to the URLs contained in the
264 ``$GLOBALS['phorkie']['cfg']['webhooks']`` setting array, with
265 a MIME type of ``application/vnd.phorkie.webhook+json``::
271 'email': 'anonymous@phorkie',
274 'name': 'webhooktest',
275 'url': 'http://example.org/33',
276 'description': 'webhooktest',
279 'email': 'anonymous@phorkie',
284 The event may be ``create``, ``edit`` or ``delete``.
298 Display page for paste
302 Edit a single file of the paste
304 Display raw file contents
305 ``/[0-9]/tool/[a-zA-Z]+/(.+)``
306 Run a tool on the given file
307 ``/[0-9]/rev/[a-z0-9]+``
308 Show specific revision of the paste
312 Show DOAP document for paste
314 Create a fork of the paste
315 ``/search?q=..(&page=[0-9]+)?``
316 Search for term, with optional page
318 List all pastes, with optional page
324 Shows form for new paste
326 Login page for protecting site
328 Check if everything is setup correctly and all dependencies are installed
330 Edit logged-in user information
333 Internal directory layout
334 =========================
339 1/ - work directory for paste #1
340 2/ - work directory for paste #2
342 1.git/ - git repository for paste #1
343 description - Description for the repository
344 2.git/ - git repository for paste #2
348 If you use nginx, place the following lines into your ``server`` block:
352 if (!-e $request_uri) {
353 rewrite ^/([0-9]+)$ /display.php?id=$1;
354 rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
355 rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
356 rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
357 rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
358 rewrite ^/([0-9]+)/edit/(.+)$ edit.php?id=$1&file=$2
359 rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
360 rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
361 rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
362 rewrite ^/([0-9]+)/rev-raw/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
363 rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
365 rewrite ^/fork-remote$ /fork-remote.php;
366 rewrite ^/help$ /help.php;
367 rewrite ^/new$ /new.php;
369 rewrite ^/feed/new$ /feed-new.php;
370 rewrite ^/feed/updated$ /feed-updated.php;
372 rewrite ^/list$ /list.php;
373 rewrite ^/list/([0-9]+)$ /list.php?page=$1;
375 rewrite ^/search$ /search.php;
376 rewrite ^/search/([0-9]+)$ /search.php?page=$1;
378 rewrite ^/login$ /login.php;
379 rewrite ^/setup$ /setup.php;
380 rewrite ^/user$ /user.php;