mention openid in dependencies
[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 phorkie in your web browser
73
74
75 Dependencies
76 ============
77 phorkie stands on the shoulders of giants.
78
79 It requires the following programs to be installed
80 on your machine:
81
82 - Git v1.7.5 or later
83 - PHP v5.3.0 or later
84 - PEAR v1.9.2 or later
85
86 ::
87
88   $ pear install versioncontrol_git-alpha
89   $ pear install services_libravatar-alpha
90   $ pear install http_request2
91   $ pear install pager
92   $ pear install date_humandiff-alpha
93   $ pear install openid-alpha
94
95   $ pear channel-discover pear.twig-project.org
96   $ pear install twig/Twig
97
98   $ pear channel-discover mediawiki.googlecode.com/svn
99   $ pear install mediawiki/geshi
100
101   $ pear channel-discover zustellzentrum.cweiske.de
102   $ pear install zz/mime_type_plaindetect-alpha
103
104   $ pear channel-discover pear.michelf.ca
105   $ pear install michelf/Markdown
106
107 Note that this version of GeSHi is a bit outdated, but it's the fastest
108 way to install it.
109 If you install it manually be sure to update the
110 path from ``data/config.default.php``.
111
112
113 ======
114 Search
115 ======
116
117 phorkie makes use of an Elasticsearch__ installation, if you have one.
118
119 It is used to provide search capabilities and the list of recent pastes.
120
121 __ http://www.elasticsearch.org/
122
123
124 Setup
125 =====
126 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
127 of the index, e.g. ::
128
129   http://localhost:9200/phorkie/
130
131 You must use a search namespace with Elasticsearch such as ``phorkie/``.
132 Run the index script to import all existing pastes into the index::
133
134   php scripts/index.php
135
136 That's all. Open phorkie in your browser, and you'll notice the search box
137 in the top menu.
138
139
140 Reset
141 =====
142 In case something really went wrong and you need to reset the search
143 index, run the following command::
144
145   $ curl -XDELETE http://localhost:9200/phorkie/
146   {"ok":true,"acknowledged"}
147
148 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
149 in the configuration file.
150
151 You may also manually run the reindexing script with::
152
153   $ php scripts/index.php
154
155
156 =====
157 HowTo
158 =====
159
160 Make git repositories clonable
161 ==============================
162 To make git repositories clonable, you need to install ``git-daemon``
163 (``git-daemon-run`` package on Debian/Ubuntu).
164
165 Make the repositories available by symlinking the paste repository
166 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
167 ``/var/cache/git``, e.g.::
168
169   $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
170
171 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
172 setting to ``git://$yourhostname/git/paste/``.
173 The rest will be appended automatically.
174
175
176 You're on your own to setup writable repositories.
177
178
179 Protect your site with OpenID
180 =============================
181 You have the option of enabling OpenID authentication to help secure your
182 pastes on phorkie.
183 Set the ``$GLOBALS['phorkie']['auth']`` values in the
184 ``data/config.php`` file as desired.
185
186 There are two different types of security you can apply.
187 First, you can restrict to one of three ``securityLevels``:
188
189 - completely open (``0``)
190 - protection of write-enabled functions such as add, edit, etc. (``1``)
191 - full site protection (``2``)
192
193 Additionally, you can restrict your site to ``listedUsersOnly``.
194 You will need to add the individual OpenID urls to the
195 ``$GLOBALS['phorkie']['auth']['users']`` variable.
196
197
198 Get information about paste editors
199 ===================================
200 Phorkie stores the user's OpenID or IP address (when not logged in) when
201 a paste is edited.
202 It is possible to get this information for each single commit::
203
204     // IP / OpenID for the latest commit
205     $ git notes --ref=identity show
206     127.0.0.1
207
208     // show IP / OpenID for a given commit
209     $ git notes --ref=identity show 29f82a
210     http://cweiske.de/
211
212
213 Notifications via webhooks
214 ==========================
215 Depending on how you use phorkie, it might be nice to notify some other service
216 when pastes are added or updated.
217 Phorkie contains a simply mechanism to post data to a given URL which
218 you can then use as needed.
219
220 The data are json-encoded POSTed to the URLs contained in the
221 ``$GLOBALS['phorkie']['cfg']['webhooks']`` setting array, with
222 a MIME type of ``application/vnd.phorkie.webhook+json``::
223
224   {
225       'event': 'create',
226       'author': {
227           'name':'Anonymous',
228           'email': 'anonymous@phorkie',
229       },
230       'repository': {
231           'name': 'webhooktest',
232           'url': 'http://example.org/33',
233           'description': 'webhooktest',
234           'owner': {
235               'name': 'Anonymous',
236               'email': 'anonymous@phorkie',
237           }
238       }
239   }
240
241 The event may be ``create``, ``edit`` or ``delete``.
242
243
244 =================
245 Technical details
246 =================
247
248 TODO
249 ====
250 - filters (``xmllint --format``, ``rapper``)
251 - document how to keep disk usage low (block size)
252 - comments
253 - when 2 people edit, merge changes
254 - diff changes
255 - configurable highlights
256 - Atom feed for new pastes
257 - Atom feed for paste changes
258
259
260 URLs
261 ====
262
263 ``/``
264   Index page.
265 ``/[0-9]+``
266   Display page for paste
267 ``/[0-9]/edit``
268   Edit the paste
269 ``/[0-9]+/raw/(.+)``
270   Display raw file contents
271 ``/[0-9]/tool/[a-zA-Z]+/(.+)``
272   Run a tool on the given file
273 ``/[0-9]/rev/[a-z0-9]+``
274   Show specific revision of the paste
275 ``/[0-9]/delete``
276   Delete the paste
277 ``/[0-9]/doap``
278   Show DOAP document for paste
279 ``/[0-9]/fork``
280   Create a fork of the paste
281 ``/search?q=..(&page=[0-9]+)?``
282   Search for term, with optional page
283 ``/list(/[0-9])?``
284   List all pastes, with optional page
285 ``/new``
286   Shows form for new paste
287 ``/login``
288   Login page for protecting site
289 ``/user``
290   Edit logged-in user information
291
292
293 Internal directory layout
294 =========================
295 ::
296
297   repos/
298     work/
299       1/ - work directory for paste #1
300       2/ - work directory for paste #2
301     git/
302       1.git/ - git repository for paste #1
303         description - Description for the repository
304       2.git/ - git repository for paste #2
305
306 nginx rewrites
307 ==============
308 If you use nginx, place the following lines into your ``server`` block:
309
310 ::
311
312   if (!-e $request_uri) {
313     rewrite ^/([0-9]+)$ /display.php?id=$1;
314     rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
315     rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
316     rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
317     rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
318     rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
319     rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
320     rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
321     rewrite ^/([0-9]+)/rev-raw/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
322     rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
323
324     rewrite ^/new$ /new.php;
325     rewrite ^/feed/new$ /feed-new.php;
326     rewrite ^/feed/updated$ /feed-updated.php;
327     rewrite ^/list$ /list.php;
328     rewrite ^/list/([0-9]+)$ /list.php?page=$1;
329
330     rewrite ^/search$ /search.php;
331     rewrite ^/search/([0-9]+)$ /search.php?page=$1;
332
333     rewrite ^/login$ /login.php;
334     rewrite ^/user$ /user.php;
335   }