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