warn about non-configured search adapter during indexing
[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   - single click forking of forks on different servers to your own
20 - paste editing
21
22   - add new files
23   - delete existing files
24   - replace file with upload
25 - multiple files in one paste
26 - syntax highlighting with GeSHi
27 - rST and Markdown rendering
28 - image upload + display
29 - OpenID authentication
30 - external tool support
31
32   - xmllint
33   - php syntax check
34 - history in the sidebar
35
36   - old files can be downloaded easily
37 - search across pastes: description, file names and file content
38
39   - options: quoting, logical and, or, not, partial words
40 - webhook support - get notified when pastes are created, edited or deleted
41 - atom feed for new and updated pastes
42 - notifies remote instances via linkbacks when a paste has been forked
43
44
45 ============
46 Installation
47 ============
48
49 .phar
50 =====
51 Download ``phorkie-0.4.0.phar`` and put it in your web server's document root
52 directory.
53
54 No further setup needed.
55
56 .. note:: Only valid if your webserver is configured to let
57    PHP handle ``.phar`` files.
58
59    Unfortunately, no Linux distribution has this activated by default.
60
61 .. warning:: PHP has some bugs in its .phar handling code (e.g. with FPM).
62
63    So currently, the ``.phar`` option is considered experimental.
64
65
66 Zip package
67 ===========
68 1. Unzip the phorkie release file::
69
70    $ tar xjvf phorkie-0.4.0.tar.bz2
71
72 2. Create the git directories::
73
74    $ mkdir -p www/repos/git www/repos/work
75    $ chmod og+w www/repos/git www/repos/work
76
77 3. Install dependencies_
78
79 4. Copy ``data/config.php.dist`` to ``data/config.php`` and adjust it
80    to your needs::
81
82    $ cp data/config.php.dist data/config.php
83    $ $EDITOR data/config.php
84
85    Look at ``config.default.php`` for values that you may adjust.
86
87 5. Set your web server's document root to ``/path/to/phorkie/www/``
88    Alternatively, you can add a symlink to the ``www`` folder into your
89    web server's existing document root tree (being careful to keep
90    main phorkie folder outside the document root for security purposes)
91    and ensure you set the ``baseurl`` config option appropriately. You
92    must also set the ``RewriteBase`` in the ``.htaccess`` file or adjust
93    the nginx configuration accordingly.
94
95 6. Open http://yourhost/setup in your web browser to see if everything
96    is working fine.
97
98 7. Go to http://yourhost/
99
100
101 Dependencies
102 ============
103 phorkie stands on the shoulders of giants.
104
105 It requires the following programs to be installed
106 on your machine:
107
108 - Git v1.7.5 or later
109 - PHP v5.3.0 or later
110 - PEAR v1.9.2 or later
111
112 ::
113
114   $ pear install versioncontrol_git-alpha
115   $ pear install services_libravatar-alpha
116   $ pear install http_request2
117   $ pear install pager
118   $ pear install date_humandiff-alpha
119   $ pear install openid-alpha
120
121   $ pear channel-discover pear.twig-project.org
122   $ pear install twig/Twig
123
124   $ pear channel-discover pear.geshi.org
125   $ pear install geshi/geshi
126
127   $ pear channel-discover zustellzentrum.cweiske.de
128   $ pear install zz/mime_type_plaindetect-alpha
129
130   $ pear channel-discover pear.michelf.ca
131   $ pear install michelf/Markdown
132
133   $ pear channel-discover pear2.php.net
134   $ pear install pear2/pear2_services_linkback-alpha
135
136
137 You can use composer to install all dependencies automatically::
138
139   $ composer install
140
141 Note that the ``.phar`` package already contains all dependencies.
142
143
144 ======
145 Search
146 ======
147
148 phorkie makes use of an Elasticsearch__ installation, if you have one.
149
150 It is used to provide search capabilities and the list of recent pastes.
151
152 __ http://www.elasticsearch.org/
153
154
155 Setup
156 =====
157 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
158 of the index, e.g. ::
159
160   http://localhost:9200/phorkie/
161
162 You must use a search namespace with Elasticsearch such as ``phorkie/``.
163 Run the index script to import all existing pastes into the index::
164
165   php scripts/index.php
166
167 That's all. Open phorkie in your browser, and you'll notice the search box
168 in the top menu.
169
170
171 Reset
172 =====
173 In case something really went wrong and you need to reset the search
174 index, run the following command::
175
176   $ curl -XDELETE http://localhost:9200/phorkie/
177   {"ok":true,"acknowledged"}
178
179 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
180 in the configuration file.
181
182 You may also manually run the reindexing script with::
183
184   $ php scripts/index.php
185
186
187 =====
188 HowTo
189 =====
190
191 Make git repositories clonable
192 ==============================
193
194 HTTP
195 ----
196 By default, the pastes are clonable via ``http`` as long as the ``repos/git/``
197 directory is within the ``www/`` directory.
198
199 No further setup needed.
200
201
202 git-daemon
203 ----------
204 You may use ``git-daemon`` to provide public ``git://`` clone urls.
205 Install the ``git-daemon-run`` package on Debian/Ubuntu.
206
207 Make the repositories available by symlinking the paste repository
208 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
209 ``/var/cache/git``, e.g.::
210
211   $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
212
213 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
214 setting to ``git://$yourhostname/git/paste/``.
215 The rest will be appended automatically.
216
217
218 You're on your own to setup writable repositories.
219
220
221 Protect your site with OpenID
222 =============================
223 You have the option of enabling OpenID authentication to help secure your
224 pastes on phorkie.
225 Set the ``$GLOBALS['phorkie']['auth']`` values in the
226 ``data/config.php`` file as desired.
227
228 There are two different types of security you can apply.
229 First, you can restrict to one of three ``securityLevels``:
230
231 - completely open (``0``)
232 - protection of write-enabled functions such as add, edit, etc. (``1``)
233 - full site protection (``2``)
234
235 Additionally, you can restrict your site to ``listedUsersOnly``.
236 You will need to add the individual OpenID urls to the
237 ``$GLOBALS['phorkie']['auth']['users']`` variable.
238
239
240 Get information about paste editors
241 ===================================
242 Phorkie stores the user's OpenID or IP address (when not logged in) when
243 a paste is edited.
244 It is possible to get this information for each single commit::
245
246     // IP / OpenID for the latest commit
247     $ git notes --ref=identity show
248     127.0.0.1
249
250     // show IP / OpenID for a given commit
251     $ git notes --ref=identity show 29f82a
252     http://cweiske.de/
253
254
255 Notifications via webhooks
256 ==========================
257 Depending on how you use phorkie, it might be nice to notify some other service
258 when pastes are added or updated.
259 Phorkie contains a simply mechanism to post data to a given URL which
260 you can then use as needed.
261
262 The data are json-encoded POSTed to the URLs contained in the
263 ``$GLOBALS['phorkie']['cfg']['webhooks']`` setting array, with
264 a MIME type of ``application/vnd.phorkie.webhook+json``::
265
266   {
267       'event': 'create',
268       'author': {
269           'name':'Anonymous',
270           'email': 'anonymous@phorkie',
271       },
272       'repository': {
273           'name': 'webhooktest',
274           'url': 'http://example.org/33',
275           'description': 'webhooktest',
276           'owner': {
277               'name': 'Anonymous',
278               'email': 'anonymous@phorkie',
279           }
280       }
281   }
282
283 The event may be ``create``, ``edit`` or ``delete``.
284
285
286 =================
287 Technical details
288 =================
289
290
291 URLs
292 ====
293
294 ``/``
295   Index page.
296 ``/[0-9]+``
297   Display page for paste
298 ``/[0-9]/edit``
299   Edit the paste
300 ``/[0-9]+/raw/(.+)``
301   Display raw file contents
302 ``/[0-9]/tool/[a-zA-Z]+/(.+)``
303   Run a tool on the given file
304 ``/[0-9]/rev/[a-z0-9]+``
305   Show specific revision of the paste
306 ``/[0-9]/delete``
307   Delete the paste
308 ``/[0-9]/doap``
309   Show DOAP document for paste
310 ``/[0-9]/fork``
311   Create a fork of the paste
312 ``/search?q=..(&page=[0-9]+)?``
313   Search for term, with optional page
314 ``/list(/[0-9])?``
315   List all pastes, with optional page
316 ``/fork-remote``
317   Fork a remote URL
318 ``/help``
319   Show help page
320 ``/new``
321   Shows form for new paste
322 ``/login``
323   Login page for protecting site
324 ``/setup``
325   Check if everything is setup correctly and all dependencies are installed
326 ``/user``
327   Edit logged-in user information
328
329
330 Internal directory layout
331 =========================
332 ::
333
334   repos/
335     work/
336       1/ - work directory for paste #1
337       2/ - work directory for paste #2
338     git/
339       1.git/ - git repository for paste #1
340         description - Description for the repository
341       2.git/ - git repository for paste #2
342
343 nginx rewrites
344 ==============
345 If you use nginx, place the following lines into your ``server`` block:
346
347 ::
348
349   if (!-e $request_uri) {
350     rewrite ^/([0-9]+)$ /display.php?id=$1;
351     rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
352     rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
353     rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
354     rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
355     rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
356     rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
357     rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
358     rewrite ^/([0-9]+)/rev-raw/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
359     rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
360
361     rewrite ^/fork-remote$ /fork-remote.php;
362     rewrite ^/help$ /help.php;
363     rewrite ^/new$ /new.php;
364     rewrite ^/feed/new$ /feed-new.php;
365     rewrite ^/feed/updated$ /feed-updated.php;
366     rewrite ^/list$ /list.php;
367     rewrite ^/list/([0-9]+)$ /list.php?page=$1;
368
369     rewrite ^/search$ /search.php;
370     rewrite ^/search/([0-9]+)$ /search.php?page=$1;
371
372     rewrite ^/login$ /login.php;
373     rewrite ^/setup$ /setup.php;
374     rewrite ^/user$ /user.php;
375   }