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
  40
  41 ============
  42 Installation
  43 ============
  44 1. Unzip the phorkie release file::
  45
  46    $ tar xjvf phorkie-0.3.0.tar.bz2
  47
  48 2. Create the git directories::
  49
  50    $ mkdir -p repos/git repos/work
  51    $ chmod og+w repos/git repos/work
  52
  53 3. Install dependencies_
  54
  55 4. Copy ``data/config.php.dist`` to ``data/config.php`` and adjust it
  56    to your needs::
  57
  58    $ cp data/config.php.dist data/config.php
  59    $ $EDITOR data/config.php
  60
  61    Look at ``config.default.php`` for values that you may adjust.
  62
  63 5. Set your web server's document root to ``/path/to/phorkie/www/``
  64    Alternatively, you can add a symlink to the ``www`` folder into your
  65    web server's existing document root tree (being careful to keep
  66    main phorkie folder outside the document root for security purposes)
  67    and ensure you set the ``baseurl`` config option appropriately. You
  68    must also set the ``RewriteBase`` in the ``.htaccess`` file or adjust
  69    the nginx configuration accordingly.
  70
  71 6. Open phorkie in your web browser
  72
  73
  74 Dependencies
  75 ============
  76 phorkie stands on the shoulders of giants.
  77
  78 It requires the following programs to be installed
  79 on your machine:
  80
  81 - Git v1.7.5 or later
  82 - PHP v5.3.0 or later
  83 - PEAR v1.9.2 or later
  84
  85 ::
  86
  87   $ pear install versioncontrol_git-alpha
  88   $ pear install services_libravatar-alpha
  89   $ pear install http_request2
  90   $ pear install pager
  91   $ pear install date_humandiff-alpha
  92
  93   $ pear channel-discover pear.twig-project.org
  94   $ pear install twig/Twig
  95
  96   $ pear channel-discover mediawiki.googlecode.com/svn
  97   $ pear install mediawiki/geshi
  98
  99   $ pear channel-discover zustellzentrum.cweiske.de
 100   $ pear install zz/mime_type_plaindetect-alpha
 101
 102   $ pear channel-discover pear.michelf.ca
 103   $ pear install michelf/Markdown
 104
 105 Note that this version of GeSHi is a bit outdated, but it's the fastest
 106 way to install it.
 107 If you install it manually be sure to update the
 108 path from ``data/config.default.php``.
 109
 110
 111 ======
 112 Search
 113 ======
 114
 115 phorkie makes use of an Elasticsearch__ installation, if you have one.
 116
 117 It is used to provide search capabilities and the list of recent pastes.
 118
 119 __ http://www.elasticsearch.org/
 120
 121
 122 Setup
 123 =====
 124 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
 125 of the index, e.g. ::
 126
 127   http://localhost:9200/phorkie/
 128
 129 You must use a search namespace with Elasticsearch such as ``phorkie/``.
 130 Run the index script to import all existing pastes into the index::
 131
 132   php scripts/index.php
 133
 134 That's all. Open phorkie in your browser, and you'll notice the search box
 135 in the top menu.
 136
 137
 138 Reset
 139 =====
 140 In case something really went wrong and you need to reset the search
 141 index, run the following command::
 142
 143   $ curl -XDELETE http://localhost:9200/phorkie/
 144   {"ok":true,"acknowledged"}
 145
 146 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
 147 in the configuration file.
 148
 149 You may also manually run the reindexing script with::
 150
 151   $ php scripts/index.php
 152
 153
 154 =====
 155 HowTo
 156 =====
 157
 158 Make git repositories clonable
 159 ==============================
 160 To make git repositories clonable, you need to install ``git-daemon``
 161 (``git-daemon-run`` package on Debian/Ubuntu).
 162
 163 Make the repositories available by symlinking the paste repository
 164 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
 165 ``/var/cache/git``, e.g.::
 166
 167   $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
 168
 169 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
 170 setting to ``git://$yourhostname/git/paste/``.
 171 The rest will be appended automatically.
 172
 173
 174 You're on your own to setup writable repositories.
 175
 176
 177 Protect your site with OpenID
 178 =============================
 179 You have the option of enabling OpenID authentication to help secure your
 180 pastes on phorkie.
 181 Set the ``$GLOBALS['phorkie']['auth']`` values in the
 182 ``data/config.php`` file as desired.
 183
 184 There are two different types of security you can apply.
 185 First, you can restrict to one of three ``securityLevels``:
 186
 187 - completely open (``0``)
 188 - protection of write-enabled functions such as add, edit, etc. (``1``)
 189 - full site protection (``2``)
 190
 191 Additionally, you can restrict your site to ``listedUsersOnly``.
 192 You will need to add the individual OpenID urls to the
 193 ``$GLOBALS['phorkie']['auth']['users']`` variable.
 194
 195
 196 Get information about paste editors
 197 ===================================
 198 Phorkie stores the user's OpenID or IP address (when not logged in) when
 199 a paste is edited.
 200 It is possible to get this information for each single commit::
 201
 202     // IP / OpenID for the latest commit
 203     $ git notes --ref=identity show
 204     127.0.0.1
 205
 206     // show IP / OpenID for a given commit
 207     $ git notes --ref=identity show 29f82a
 208     http://cweiske.de/
 209
 210
 211 =================
 212 Technical details
 213 =================
 214
 215 TODO
 216 ====
 217 - filters (``xmllint --format``, ``rapper``)
 218 - document how to keep disk usage low (block size)
 219 - comments
 220 - when 2 people edit, merge changes
 221 - diff changes
 222 - configurable highlights
 223 - Atom feed for new pastes
 224 - Atom feed for paste changes
 225
 226
 227 URLs
 228 ====
 229
 230 ``/``
 231   Index page.
 232 ``/[0-9]+``
 233   Display page for paste
 234 ``/[0-9]/edit``
 235   Edit the paste
 236 ``/[0-9]+/raw/(.+)``
 237   Display raw file contents
 238 ``/[0-9]/tool/[a-zA-Z]+/(.+)``
 239   Run a tool on the given file
 240 ``/[0-9]/rev/[a-z0-9]+``
 241   Show specific revision of the paste
 242 ``/[0-9]/delete``
 243   Delete the paste
 244 ``/[0-9]/doap``
 245   Show DOAP document for paste
 246 ``/[0-9]/fork``
 247   Create a fork of the paste
 248 ``/search?q=..(&page=[0-9]+)?``
 249   Search for term, with optional page
 250 ``/list(/[0-9])?``
 251   List all pastes, with optional page
 252 ``/new``
 253   Shows form for new paste
 254 ``/login``
 255   Login page for protecting site
 256 ``/user``
 257   Edit logged-in user information
 258
 259
 260 Internal directory layout
 261 =========================
 262 ::
 263
 264   repos/
 265     work/
 266       1/ - work directory for paste #1
 267       2/ - work directory for paste #2
 268     git/
 269       1.git/ - git repository for paste #1
 270         description - Description for the repository
 271       2.git/ - git repository for paste #2
 272
 273 nginx rewrites
 274 ==============
 275 If you use nginx, place the following lines into your ``server`` block:
 276
 277 ::
 278
 279   if (!-e $request_uri) {
 280     rewrite ^/([0-9]+)$ /display.php?id=$1;
 281     rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
 282     rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
 283     rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
 284     rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
 285     rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
 286     rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
 287     rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
 288     rewrite ^/([0-9]+)/rev-raw/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
 289     rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
 290
 291     rewrite ^/new$ /new.php;
 292     rewrite ^/feed/new$ /feed-new.php;
 293     rewrite ^/feed/updated$ /feed-updated.php;
 294     rewrite ^/list$ /list.php;
 295     rewrite ^/list/([0-9]+)$ /list.php?page=$1;
 296
 297     rewrite ^/search$ /search.php;
 298     rewrite ^/search/([0-9]+)$ /search.php?page=$1;
 299
 300     rewrite ^/login$ /login.php;
 301     rewrite ^/user$ /user.php;
 302   }