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