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