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   }