use geshi from geshi's new pear channel
[phorkie.git] / README.rst
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.
6
7 Project page: http://sourceforge.net/p/phorkie/
8
9 .. contents:: Table of Contents
10
11 ========
12 Features
13 ========
14 - every paste is a git repository
15
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 - paste editing
20
21   - add new files
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
30
31   - xmllint
32   - php syntax check
33 - history in the sidebar
34
35   - old files can be downloaded easily
36 - search across pastes: description, file names and file content
37
38   - options: quoting, logical and, or, not, partial words
39 - webhook support - get notified when pastes are created, edited or deleted
40
41
42 ============
43 Installation
44 ============
45 1. Unzip the phorkie release file::
46
47    $ tar xjvf phorkie-0.3.0.tar.bz2
48
49 2. Create the git directories::
50
51    $ mkdir -p repos/git repos/work
52    $ chmod og+w repos/git repos/work
53
54 3. Install dependencies_
55
56 4. Copy ``data/config.php.dist`` to ``data/config.php`` and adjust it
57    to your needs::
58
59    $ cp data/config.php.dist data/config.php
60    $ $EDITOR data/config.php
61
62    Look at ``config.default.php`` for values that you may adjust.
63
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.
71
72 6. Open http://yourhost/setup in your web browser to see if everything
73    is working fine.
74
75 7. Go to http://yourhost/
76
77
78 Dependencies
79 ============
80 phorkie stands on the shoulders of giants.
81
82 It requires the following programs to be installed
83 on your machine:
84
85 - Git v1.7.5 or later
86 - PHP v5.3.0 or later
87 - PEAR v1.9.2 or later
88
89 ::
90
91   $ pear install versioncontrol_git-alpha
92   $ pear install services_libravatar-alpha
93   $ pear install http_request2
94   $ pear install pager
95   $ pear install date_humandiff-alpha
96   $ pear install openid-alpha
97
98   $ pear channel-discover pear.twig-project.org
99   $ pear install twig/Twig
100
101   $ pear channel-discover pear.geshi.org
102   $ pear install geshi/geshi
103
104   $ pear channel-discover zustellzentrum.cweiske.de
105   $ pear install zz/mime_type_plaindetect-alpha
106
107   $ pear channel-discover pear.michelf.ca
108   $ pear install michelf/Markdown
109
110   $ pear channel-discover pear2.php.net
111   $ pear install pear2/pear2_services_linkback-alpha
112
113
114 ======
115 Search
116 ======
117
118 phorkie makes use of an Elasticsearch__ installation, if you have one.
119
120 It is used to provide search capabilities and the list of recent pastes.
121
122 __ http://www.elasticsearch.org/
123
124
125 Setup
126 =====
127 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
128 of the index, e.g. ::
129
130   http://localhost:9200/phorkie/
131
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::
134
135   php scripts/index.php
136
137 That's all. Open phorkie in your browser, and you'll notice the search box
138 in the top menu.
139
140
141 Reset
142 =====
143 In case something really went wrong and you need to reset the search
144 index, run the following command::
145
146   $ curl -XDELETE http://localhost:9200/phorkie/
147   {"ok":true,"acknowledged"}
148
149 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
150 in the configuration file.
151
152 You may also manually run the reindexing script with::
153
154   $ php scripts/index.php
155
156
157 =====
158 HowTo
159 =====
160
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).
165
166 Make the repositories available by symlinking the paste repository
167 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
168 ``/var/cache/git``, e.g.::
169
170   $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
171
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.
175
176
177 You're on your own to setup writable repositories.
178
179
180 Protect your site with OpenID
181 =============================
182 You have the option of enabling OpenID authentication to help secure your
183 pastes on phorkie.
184 Set the ``$GLOBALS['phorkie']['auth']`` values in the
185 ``data/config.php`` file as desired.
186
187 There are two different types of security you can apply.
188 First, you can restrict to one of three ``securityLevels``:
189
190 - completely open (``0``)
191 - protection of write-enabled functions such as add, edit, etc. (``1``)
192 - full site protection (``2``)
193
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.
197
198
199 Get information about paste editors
200 ===================================
201 Phorkie stores the user's OpenID or IP address (when not logged in) when
202 a paste is edited.
203 It is possible to get this information for each single commit::
204
205     // IP / OpenID for the latest commit
206     $ git notes --ref=identity show
207     127.0.0.1
208
209     // show IP / OpenID for a given commit
210     $ git notes --ref=identity show 29f82a
211     http://cweiske.de/
212
213
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.
220
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``::
224
225   {
226       'event': 'create',
227       'author': {
228           'name':'Anonymous',
229           'email': 'anonymous@phorkie',
230       },
231       'repository': {
232           'name': 'webhooktest',
233           'url': 'http://example.org/33',
234           'description': 'webhooktest',
235           'owner': {
236               'name': 'Anonymous',
237               'email': 'anonymous@phorkie',
238           }
239       }
240   }
241
242 The event may be ``create``, ``edit`` or ``delete``.
243
244
245 =================
246 Technical details
247 =================
248
249 TODO
250 ====
251 - filters (``xmllint --format``, ``rapper``)
252 - document how to keep disk usage low (block size)
253 - comments
254 - when 2 people edit, merge changes
255 - diff changes
256 - configurable highlights
257 - Atom feed for new pastes
258 - Atom feed for paste changes
259
260
261 URLs
262 ====
263
264 ``/``
265   Index page.
266 ``/[0-9]+``
267   Display page for paste
268 ``/[0-9]/edit``
269   Edit the paste
270 ``/[0-9]+/raw/(.+)``
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
276 ``/[0-9]/delete``
277   Delete the paste
278 ``/[0-9]/doap``
279   Show DOAP document for paste
280 ``/[0-9]/fork``
281   Create a fork of the paste
282 ``/search?q=..(&page=[0-9]+)?``
283   Search for term, with optional page
284 ``/list(/[0-9])?``
285   List all pastes, with optional page
286 ``/fork-remote``
287   Fork a remote URL
288 ``/help``
289   Show help page
290 ``/new``
291   Shows form for new paste
292 ``/login``
293   Login page for protecting site
294 ``/setup``
295   Check if everything is setup correctly and all dependencies are installed
296 ``/user``
297   Edit logged-in user information
298
299
300 Internal directory layout
301 =========================
302 ::
303
304   repos/
305     work/
306       1/ - work directory for paste #1
307       2/ - work directory for paste #2
308     git/
309       1.git/ - git repository for paste #1
310         description - Description for the repository
311       2.git/ - git repository for paste #2
312
313 nginx rewrites
314 ==============
315 If you use nginx, place the following lines into your ``server`` block:
316
317 ::
318
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;
330
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;
338
339     rewrite ^/search$ /search.php;
340     rewrite ^/search/([0-9]+)$ /search.php?page=$1;
341
342     rewrite ^/login$ /login.php;
343     rewrite ^/setup$ /setup.php;
344     rewrite ^/user$ /user.php;
345   }