d41d89bf61f9f5e9e7878d50802b1405473adf3f
[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 - paste editing
19
20   - add new files
21   - delete existing files
22   - replace file with upload
23 - multiple files in one paste
24 - syntax highlighting with GeSHi
25 - rST rendering
26 - image upload + display
27 - external tool support
28
29   - xmllint
30   - php syntax check
31 - history in the sidebar
32
33   - old files can be downloaded easily
34 - search across pastes: description, file names and file content
35
36   - options: quoting, logical and, or, not, partial words
37
38
39 ============
40 Installation
41 ============
42 1. Unzip the phorkie release file::
43
44    $ tar xjvf phorkie-0.2.0.tar.bz2
45
46 2. Create the git directories::
47
48    $ mkdir -p repos/git repos/work
49    $ chmod og+w repos/git repos/work
50
51 3. Install dependencies_
52
53 4. Copy ``data/config.php.dist`` to ``data/config.php`` and adjust it
54    to your needs::
55
56    $ cp data/config.php.dist data/config.php
57    $ $EDITOR data/config.php
58
59    Look at ``config.default.php`` for values that you may adjust.
60
61 5. Set your web server's document root to ``/path/to/phorkie-0.2.0/www/``
62
63 6. Open phorkie in your web browser
64
65
66 Dependencies
67 ============
68 phorkie stands on the shoulders of giants.
69
70 ::
71
72   $ pear install versioncontrol_git-alpha
73   $ pear install services_libravatar-alpha
74   $ pear install http_request2
75   $ pear install pager
76   $ pear install date_humandiff-alpha
77
78   $ pear channel-discover pear.twig-project.org
79   $ pear install twig/Twig
80
81   $ pear channel-discover mediawiki.googlecode.com/svn
82   $ pear install mediawiki/geshi
83
84   $ pear channel-discover zustellzentrum.cweiske.de
85   $ pear install zz/mime_type_plaindetect-alpha
86
87   $ pear channel-discover pear.michelf.ca
88   $ pear install michelf/Markdown
89
90 Note that this version of GeSHi is a bit outdated, but it's the fastest
91 way to install it.
92
93
94 ======
95 Search
96 ======
97
98 phorkie makes use of an Elasticsearch__ installation if you have one.
99
100 It is used to provide search capabilities and the list of recent pastes.
101
102 __ http://www.elasticsearch.org/
103
104 Setup
105 =====
106 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
107 of the index, e.g. ::
108
109   http://localhost:9200/phorkie/
110
111 Run the index script to import all existing pastes into the index::
112
113   php scripts/index.php
114
115 That's all. Open phorkie in your browser, and you'll notice the search box
116 in the top menu.
117
118
119 Reset
120 =====
121 In case something really went wrong and you need to reset the search
122 index, run the following command::
123
124   $ curl -XDELETE http://localhost:9200/phorkie/
125   {"ok":true,"acknowledged"}
126
127 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
128 in the configuration file.
129
130
131 =====
132 HowTo
133 =====
134
135 Make git repositories clonable
136 ==============================
137 To make git repositories clonable, you need to install ``git-daemon``
138 (``git-daemon-run`` package on Debian/Ubuntu).
139
140 Now make the repositories available by symlinking the paste repository
141 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
142 ``/var/cache/git``, e.g.::
143
144   $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
145
146 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
147 setting to ``git://$yourhostname/git/paste/``.
148 The rest will be appended automatically.
149
150
151 You're on your own to setup writable repositories.
152
153
154 =================
155 Technical details
156 =================
157
158 TODO
159 ====
160 - OpenID-Login to get username+email as authorship information
161 - filters (``xmllint --format``, ``rapper``)
162 - document how to keep disk usage low (block size)
163 - comments
164 - when 2 people edit, merge changes
165 - diff changes
166 - configurable highlights
167 - Atom feed for new pastes
168 - Atom feed for paste changes
169
170
171 URLs
172 ====
173
174 ``/``
175   Index page.
176 ``/[0-9]+``
177   Display page for paste
178 ``/[0-9]/edit``
179   Edit the paste
180 ``/[0-9]+/raw/(.+)``
181   Display raw file contents
182 ``/[0-9]/tool/[a-zA-Z]+/(.+)``
183   Run a tool on the given file
184 ``/[0-9]/rev/[a-z0-9]+``
185   Show specific revision of the paste
186 ``/[0-9]/delete``
187   Delete the paste
188 ``/[0-9]/doap``
189   Show DOAP document for paste
190 ``/[0-9]/fork``
191   Create a fork of the paste
192 ``/search?q=..(&page=[0-9]+)?``
193   Search for term, with optional page
194 ``/list(/[0-9])?``
195   List all pastes, with optional page
196 ``/new``
197   Shows form for new paste
198 ``/login``
199   Login page for protecting site
200 ``/user``
201   Edit logged-in user information
202
203
204 Internal directory layout
205 =========================
206 ::
207
208   repos/
209     work/
210       1/ - work directory for paste #1
211       2/ - work directory for paste #2
212     git/
213       1.git/ - git repository for paste #1
214         description - Description for the repository
215       2.git/ - git repository for paste #2
216
217 nginx rewrites
218 ==============
219 If you use nginx, place the following lines into your ``server`` block:
220
221 ::
222
223   if (!-e $request_uri) {
224     rewrite ^/([0-9]+)$ /display.php?id=$1;
225     rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
226     rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
227     rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
228     rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
229     rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
230     rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
231     rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
232     rewrite ^/([0-9]+)/rev-raw/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
233     rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
234
235     rewrite ^/new$ /new.php;
236     rewrite ^/list$ /list.php;
237     rewrite ^/list/([0-9]+)$ /list.php?page=$1;
238
239     rewrite ^/search$ /search.php;
240     rewrite ^/search/([0-9]+)$ /search.php?page=$1;
241
242     rewrite ^/login$ /login.php;
243     rewrite ^/user$ /user.php;
244   }