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 pear.geshi.org
102 $ pear install geshi/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
118 phorkie makes use of an Elasticsearch__ installation, if you have one.
120 It is used to provide search capabilities and the list of recent pastes.
122 __ http://www.elasticsearch.org/
127 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
128 of the index, e.g. ::
130 http://localhost:9200/phorkie/
132 You must use a search namespace with Elasticsearch such as ``phorkie/``.
133 Run the index script to import all existing pastes into the index::
135 php scripts/index.php
137 That's all. Open phorkie in your browser, and you'll notice the search box
143 In case something really went wrong and you need to reset the search
144 index, run the following command::
146 $ curl -XDELETE http://localhost:9200/phorkie/
147 {"ok":true,"acknowledged"}
149 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
150 in the configuration file.
152 You may also manually run the reindexing script with::
154 $ php scripts/index.php
161 Make git repositories clonable
162 ==============================
163 To make git repositories clonable, you need to install ``git-daemon``
164 (``git-daemon-run`` package on Debian/Ubuntu).
166 Make the repositories available by symlinking the paste repository
167 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
168 ``/var/cache/git``, e.g.::
170 $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
172 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
173 setting to ``git://$yourhostname/git/paste/``.
174 The rest will be appended automatically.
177 You're on your own to setup writable repositories.
180 Protect your site with OpenID
181 =============================
182 You have the option of enabling OpenID authentication to help secure your
184 Set the ``$GLOBALS['phorkie']['auth']`` values in the
185 ``data/config.php`` file as desired.
187 There are two different types of security you can apply.
188 First, you can restrict to one of three ``securityLevels``:
190 - completely open (``0``)
191 - protection of write-enabled functions such as add, edit, etc. (``1``)
192 - full site protection (``2``)
194 Additionally, you can restrict your site to ``listedUsersOnly``.
195 You will need to add the individual OpenID urls to the
196 ``$GLOBALS['phorkie']['auth']['users']`` variable.
199 Get information about paste editors
200 ===================================
201 Phorkie stores the user's OpenID or IP address (when not logged in) when
203 It is possible to get this information for each single commit::
205 // IP / OpenID for the latest commit
206 $ git notes --ref=identity show
209 // show IP / OpenID for a given commit
210 $ git notes --ref=identity show 29f82a
214 Notifications via webhooks
215 ==========================
216 Depending on how you use phorkie, it might be nice to notify some other service
217 when pastes are added or updated.
218 Phorkie contains a simply mechanism to post data to a given URL which
219 you can then use as needed.
221 The data are json-encoded POSTed to the URLs contained in the
222 ``$GLOBALS['phorkie']['cfg']['webhooks']`` setting array, with
223 a MIME type of ``application/vnd.phorkie.webhook+json``::
229 'email': 'anonymous@phorkie',
232 'name': 'webhooktest',
233 'url': 'http://example.org/33',
234 'description': 'webhooktest',
237 'email': 'anonymous@phorkie',
242 The event may be ``create``, ``edit`` or ``delete``.
251 - filters (``xmllint --format``, ``rapper``)
252 - document how to keep disk usage low (block size)
254 - when 2 people edit, merge changes
256 - configurable highlights
257 - Atom feed for new pastes
258 - Atom feed for paste changes
267 Display page for paste
271 Display raw file contents
272 ``/[0-9]/tool/[a-zA-Z]+/(.+)``
273 Run a tool on the given file
274 ``/[0-9]/rev/[a-z0-9]+``
275 Show specific revision of the paste
279 Show DOAP document for paste
281 Create a fork of the paste
282 ``/search?q=..(&page=[0-9]+)?``
283 Search for term, with optional page
285 List all pastes, with optional page
291 Shows form for new paste
293 Login page for protecting site
295 Check if everything is setup correctly and all dependencies are installed
297 Edit logged-in user information
300 Internal directory layout
301 =========================
306 1/ - work directory for paste #1
307 2/ - work directory for paste #2
309 1.git/ - git repository for paste #1
310 description - Description for the repository
311 2.git/ - git repository for paste #2
315 If you use nginx, place the following lines into your ``server`` block:
319 if (!-e $request_uri) {
320 rewrite ^/([0-9]+)$ /display.php?id=$1;
321 rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
322 rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
323 rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
324 rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
325 rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
326 rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
327 rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
328 rewrite ^/([0-9]+)/rev-raw/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
329 rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
331 rewrite ^/fork-remote$ /fork-remote.php;
332 rewrite ^/help$ /help.php;
333 rewrite ^/new$ /new.php;
334 rewrite ^/feed/new$ /feed-new.php;
335 rewrite ^/feed/updated$ /feed-updated.php;
336 rewrite ^/list$ /list.php;
337 rewrite ^/list/([0-9]+)$ /list.php?page=$1;
339 rewrite ^/search$ /search.php;
340 rewrite ^/search/([0-9]+)$ /search.php?page=$1;
342 rewrite ^/login$ /login.php;
343 rewrite ^/setup$ /setup.php;
344 rewrite ^/user$ /user.php;