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)
22 - delete existing files
23 - replace file with upload
24 - multiple files in one paste
25 - syntax highlighting with GeSHi
26 - rST and Markdown rendering
27 - image upload + display
28 - OpenID authentication
29 - external tool support
33 - history in the sidebar
35 - old files can be downloaded easily
36 - search across pastes: description, file names and file content
38 - options: quoting, logical and, or, not, partial words
39 - webhook support - get notified when pastes are created, edited or deleted
45 1. Unzip the phorkie release file::
47 $ tar xjvf phorkie-0.3.0.tar.bz2
49 2. Create the git directories::
51 $ mkdir -p repos/git repos/work
52 $ chmod og+w repos/git repos/work
54 3. Install dependencies_
56 4. Copy ``data/config.php.dist`` to ``data/config.php`` and adjust it
59 $ cp data/config.php.dist data/config.php
60 $ $EDITOR data/config.php
62 Look at ``config.default.php`` for values that you may adjust.
64 5. Set your web server's document root to ``/path/to/phorkie/www/``
65 Alternatively, you can add a symlink to the ``www`` folder into your
66 web server's existing document root tree (being careful to keep
67 main phorkie folder outside the document root for security purposes)
68 and ensure you set the ``baseurl`` config option appropriately. You
69 must also set the ``RewriteBase`` in the ``.htaccess`` file or adjust
70 the nginx configuration accordingly.
72 6. Open http://yourhost/setup in your web browser to see if everything
75 7. Go to http://yourhost/
80 phorkie stands on the shoulders of giants.
82 It requires the following programs to be installed
87 - PEAR v1.9.2 or later
91 $ pear install versioncontrol_git-alpha
92 $ pear install services_libravatar-alpha
93 $ pear install http_request2
95 $ pear install date_humandiff-alpha
96 $ pear install openid-alpha
98 $ pear channel-discover pear.twig-project.org
99 $ pear install twig/Twig
101 $ pear channel-discover mediawiki.googlecode.com/svn
102 $ pear install mediawiki/geshi
104 $ pear channel-discover zustellzentrum.cweiske.de
105 $ pear install zz/mime_type_plaindetect-alpha
107 $ pear channel-discover pear.michelf.ca
108 $ pear install michelf/Markdown
110 $ pear channel-discover pear2.php.net
111 $ pear install pear2/pear2_services_linkback-alpha
113 Note that this version of GeSHi is a bit outdated, but it's the fastest
115 If you install it manually be sure to update the
116 path from ``data/config.default.php``.
123 phorkie makes use of an Elasticsearch__ installation, if you have one.
125 It is used to provide search capabilities and the list of recent pastes.
127 __ http://www.elasticsearch.org/
132 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
133 of the index, e.g. ::
135 http://localhost:9200/phorkie/
137 You must use a search namespace with Elasticsearch such as ``phorkie/``.
138 Run the index script to import all existing pastes into the index::
140 php scripts/index.php
142 That's all. Open phorkie in your browser, and you'll notice the search box
148 In case something really went wrong and you need to reset the search
149 index, run the following command::
151 $ curl -XDELETE http://localhost:9200/phorkie/
152 {"ok":true,"acknowledged"}
154 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
155 in the configuration file.
157 You may also manually run the reindexing script with::
159 $ php scripts/index.php
166 Make git repositories clonable
167 ==============================
168 To make git repositories clonable, you need to install ``git-daemon``
169 (``git-daemon-run`` package on Debian/Ubuntu).
171 Make the repositories available by symlinking the paste repository
172 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
173 ``/var/cache/git``, e.g.::
175 $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
177 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
178 setting to ``git://$yourhostname/git/paste/``.
179 The rest will be appended automatically.
182 You're on your own to setup writable repositories.
185 Protect your site with OpenID
186 =============================
187 You have the option of enabling OpenID authentication to help secure your
189 Set the ``$GLOBALS['phorkie']['auth']`` values in the
190 ``data/config.php`` file as desired.
192 There are two different types of security you can apply.
193 First, you can restrict to one of three ``securityLevels``:
195 - completely open (``0``)
196 - protection of write-enabled functions such as add, edit, etc. (``1``)
197 - full site protection (``2``)
199 Additionally, you can restrict your site to ``listedUsersOnly``.
200 You will need to add the individual OpenID urls to the
201 ``$GLOBALS['phorkie']['auth']['users']`` variable.
204 Get information about paste editors
205 ===================================
206 Phorkie stores the user's OpenID or IP address (when not logged in) when
208 It is possible to get this information for each single commit::
210 // IP / OpenID for the latest commit
211 $ git notes --ref=identity show
214 // show IP / OpenID for a given commit
215 $ git notes --ref=identity show 29f82a
219 Notifications via webhooks
220 ==========================
221 Depending on how you use phorkie, it might be nice to notify some other service
222 when pastes are added or updated.
223 Phorkie contains a simply mechanism to post data to a given URL which
224 you can then use as needed.
226 The data are json-encoded POSTed to the URLs contained in the
227 ``$GLOBALS['phorkie']['cfg']['webhooks']`` setting array, with
228 a MIME type of ``application/vnd.phorkie.webhook+json``::
234 'email': 'anonymous@phorkie',
237 'name': 'webhooktest',
238 'url': 'http://example.org/33',
239 'description': 'webhooktest',
242 'email': 'anonymous@phorkie',
247 The event may be ``create``, ``edit`` or ``delete``.
256 - filters (``xmllint --format``, ``rapper``)
257 - document how to keep disk usage low (block size)
259 - when 2 people edit, merge changes
261 - configurable highlights
262 - Atom feed for new pastes
263 - Atom feed for paste changes
272 Display page for paste
276 Display raw file contents
277 ``/[0-9]/tool/[a-zA-Z]+/(.+)``
278 Run a tool on the given file
279 ``/[0-9]/rev/[a-z0-9]+``
280 Show specific revision of the paste
284 Show DOAP document for paste
286 Create a fork of the paste
287 ``/search?q=..(&page=[0-9]+)?``
288 Search for term, with optional page
290 List all pastes, with optional page
296 Shows form for new paste
298 Login page for protecting site
300 Check if everything is setup correctly and all dependencies are installed
302 Edit logged-in user information
305 Internal directory layout
306 =========================
311 1/ - work directory for paste #1
312 2/ - work directory for paste #2
314 1.git/ - git repository for paste #1
315 description - Description for the repository
316 2.git/ - git repository for paste #2
320 If you use nginx, place the following lines into your ``server`` block:
324 if (!-e $request_uri) {
325 rewrite ^/([0-9]+)$ /display.php?id=$1;
326 rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
327 rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
328 rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
329 rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
330 rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
331 rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
332 rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
333 rewrite ^/([0-9]+)/rev-raw/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
334 rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
336 rewrite ^/fork-remote$ /fork-remote.php;
337 rewrite ^/help$ /help.php;
338 rewrite ^/new$ /new.php;
339 rewrite ^/feed/new$ /feed-new.php;
340 rewrite ^/feed/updated$ /feed-updated.php;
341 rewrite ^/list$ /list.php;
342 rewrite ^/list/([0-9]+)$ /list.php?page=$1;
344 rewrite ^/search$ /search.php;
345 rewrite ^/search/([0-9]+)$ /search.php?page=$1;
347 rewrite ^/login$ /login.php;
348 rewrite ^/setup$ /setup.php;
349 rewrite ^/user$ /user.php;