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   - single click forking of forks on different servers to your own
  20 - paste editing
  21
  22   - add new files
  23   - delete existing files
  24   - replace file with upload
  25 - embedding of pastes in your blog (via JavaScript or oEmbed)
  26 - multiple files in one paste
  27   - option to edit single files in a multi-file paste
  28 - syntax highlighting with GeSHi
  29 - rST and Markdown rendering
  30 - image upload + display
  31 - OpenID authentication
  32 - external tool support
  33
  34   - xmllint
  35   - php syntax check
  36 - history in the sidebar
  37
  38   - old files can be downloaded easily
  39 - search across pastes: description, file names and file content
  40
  41   - options: quoting, logical and, or, not, partial words
  42 - webhook support - get notified when pastes are created, edited or deleted
  43 - atom feed for new and updated pastes
  44 - notifies remote instances via linkbacks when a paste has been forked
  45
  46
  47 ============
  48 Installation
  49 ============
  50
  51 .phar
  52 =====
  53 Download ``phorkie-0.5.0.phar`` and put it in your web server's document root
  54 directory.
  55
  56 No further setup needed.
  57
  58 .. note:: Only valid if your webserver is configured to let
  59    PHP handle ``.phar`` files.
  60
  61    Unfortunately, no Linux distribution has this activated by default.
  62
  63 .. warning:: PHP has some bugs in its .phar handling code (e.g. with FPM).
  64
  65    So currently, the ``.phar`` option is considered experimental.
  66
  67
  68 Zip package
  69 ===========
  70 1. Unzip the phorkie release file::
  71
  72    $ tar xjvf phorkie-0.5.0.tar.bz2
  73
  74 2. Create the git directories::
  75
  76    $ mkdir -p www/repos/git www/repos/work
  77    $ chmod og+w www/repos/git www/repos/work
  78
  79 3. Install dependencies_
  80
  81 4. Copy ``data/config.php.dist`` to ``data/config.php`` and adjust it
  82    to your needs::
  83
  84    $ cp data/config.php.dist data/config.php
  85    $ $EDITOR data/config.php
  86
  87    Look at ``config.default.php`` for values that you may adjust.
  88
  89 5. Set your web server's document root to ``/path/to/phorkie/www/``
  90    Alternatively, you can add a symlink to the ``www`` folder into your
  91    web server's existing document root tree (being careful to keep
  92    main phorkie folder outside the document root for security purposes)
  93    and ensure you set the ``baseurl`` config option appropriately. You
  94    must also set the ``RewriteBase`` in the ``.htaccess`` file or adjust
  95    the nginx configuration accordingly.
  96
  97 6. Open http://yourhost/setup in your web browser to see if everything
  98    is working fine.
  99
 100 7. Go to http://yourhost/
 101
 102
 103 Dependencies
 104 ============
 105 phorkie stands on the shoulders of giants.
 106
 107 It requires the following programs to be installed
 108 on your machine:
 109
 110 - Git v1.7.5 or later
 111 - PHP v5.3.0 or later
 112 - PEAR v1.9.2 or later
 113
 114 ::
 115
 116   $ pear install versioncontrol_git-alpha
 117   $ pear install services_libravatar-alpha
 118   $ pear install http_request2
 119   $ pear install pager
 120   $ pear install date_humandiff-alpha
 121   $ pear install openid-alpha
 122
 123   $ pear channel-discover pear.twig-project.org
 124   $ pear install twig/Twig
 125
 126   $ pear channel-discover pear.geshi.org
 127   $ pear install geshi/geshi
 128
 129   $ pear channel-discover zustellzentrum.cweiske.de
 130   $ pear install zz/mime_type_plaindetect-alpha
 131
 132   $ pear channel-discover pear.michelf.ca
 133   $ pear install michelf/Markdown
 134
 135   $ pear channel-discover pear2.php.net
 136   $ pear install pear2/pear2_services_linkback-alpha
 137
 138
 139 You can use composer to install all dependencies automatically::
 140
 141   $ composer install
 142
 143 Note that the ``.phar`` package already contains all dependencies.
 144
 145
 146 ======
 147 Search
 148 ======
 149
 150 phorkie makes use of an Elasticsearch__ installation, if you have one.
 151
 152 It is used to provide search capabilities and the list of recent pastes.
 153
 154 Elasticsearch version 1.3 is supported.
 155
 156 __ http://www.elasticsearch.org/
 157
 158
 159 Setup
 160 =====
 161 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
 162 of the index, e.g. ::
 163
 164   http://localhost:9200/phorkie/
 165
 166 You must use a search namespace with Elasticsearch such as ``phorkie/``.
 167 Run the index script to import all existing pastes into the index::
 168
 169   php scripts/index.php
 170
 171 That's all. Open phorkie in your browser, and you'll notice the search box
 172 in the top menu.
 173
 174
 175 Reset
 176 =====
 177 In case something really went wrong and you need to reset the search
 178 index, run the following command::
 179
 180   $ curl -XDELETE http://localhost:9200/phorkie/
 181   {"ok":true,"acknowledged"}
 182
 183 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
 184 in the configuration file.
 185
 186 You may also manually run the reindexing script with::
 187
 188   $ php scripts/index.php
 189
 190
 191 =====
 192 HowTo
 193 =====
 194
 195 Make git repositories clonable
 196 ==============================
 197
 198 HTTP
 199 ----
 200 By default, the pastes are clonable via ``http`` as long as the ``repos/git/``
 201 directory is within the ``www/`` directory.
 202
 203 No further setup needed.
 204
 205
 206 git-daemon
 207 ----------
 208 You may use ``git-daemon`` to provide public ``git://`` clone urls.
 209 Install the ``git-daemon-run`` package on Debian/Ubuntu.
 210
 211 Make the repositories available by symlinking the paste repository
 212 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
 213 ``/var/cache/git``, e.g.::
 214
 215   $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
 216
 217 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
 218 setting to ``git://$yourhostname/git/paste/``.
 219 The rest will be appended automatically.
 220
 221
 222 You're on your own to setup writable repositories.
 223
 224
 225 Protect your site with OpenID
 226 =============================
 227 You have the option of enabling OpenID authentication to help secure your
 228 pastes on phorkie.
 229 Set the ``$GLOBALS['phorkie']['auth']`` values in the
 230 ``data/config.php`` file as desired.
 231
 232 There are two different types of security you can apply.
 233 First, you can restrict to one of three ``securityLevels``:
 234
 235 - completely open (``0``)
 236 - protection of write-enabled functions such as add, edit, etc. (``1``)
 237 - full site protection (``2``)
 238
 239 Additionally, you can restrict your site to ``listedUsersOnly``.
 240 You will need to add the individual OpenID urls to the
 241 ``$GLOBALS['phorkie']['auth']['users']`` variable.
 242
 243
 244 Get information about paste editors
 245 ===================================
 246 Phorkie stores the user's OpenID or IP address (when not logged in) when
 247 a paste is edited.
 248 It is possible to get this information for each single commit::
 249
 250     // IP / OpenID for the latest commit
 251     $ git notes --ref=identity show
 252     127.0.0.1
 253
 254     // show IP / OpenID for a given commit
 255     $ git notes --ref=identity show 29f82a
 256     http://cweiske.de/
 257
 258
 259 Notifications via webhooks
 260 ==========================
 261 Depending on how you use phorkie, it might be nice to notify some other service
 262 when pastes are added or updated.
 263 Phorkie contains a simply mechanism to post data to a given URL which
 264 you can then use as needed.
 265
 266 The data are json-encoded POSTed to the URLs contained in the
 267 ``$GLOBALS['phorkie']['cfg']['webhooks']`` setting array, with
 268 a MIME type of ``application/vnd.phorkie.webhook+json``::
 269
 270   {
 271       'event': 'create',
 272       'author': {
 273           'name':'Anonymous',
 274           'email': 'anonymous@phorkie',
 275       },
 276       'repository': {
 277           'name': 'webhooktest',
 278           'url': 'http://example.org/33',
 279           'description': 'webhooktest',
 280           'owner': {
 281               'name': 'Anonymous',
 282               'email': 'anonymous@phorkie',
 283           }
 284       }
 285   }
 286
 287 The event may be ``create``, ``edit`` or ``delete``.
 288
 289
 290 =================
 291 Technical details
 292 =================
 293
 294
 295 URLs
 296 ====
 297
 298 ``/``
 299   Index page.
 300 ``/[0-9]+``
 301   Display page for paste
 302 ``/[0-9]+/edit``
 303   Edit the paste
 304 ``/[0-9]+/edit/(.+)``
 305   Edit a single file of the paste
 306 ``/[0-9]+/embed``
 307   JavaScript code that embeds the whole paste in a HTML page
 308 ``/[0-9]+/embed/(.+)``
 309   JavaScript code that embeds a single file in a HTML page
 310 ``/[0-9]+/raw/(.+)``
 311   Display raw file contents
 312 ``/[0-9]+/tool/[a-zA-Z]+/(.+)``
 313   Run a tool on the given file
 314 ``/[0-9]+/rev/[a-z0-9]+``
 315   Show specific revision of the paste
 316 ``/[0-9]+/delete``
 317   Delete the paste
 318 ``/[0-9]+/doap``
 319   Show DOAP document for paste
 320 ``/[0-9]+/fork``
 321   Create a fork of the paste
 322 ``/search?q=..(&page=[0-9]+)?``
 323   Search for term, with optional page
 324 ``/list(/[0-9]+)?``
 325   List all pastes, with optional page
 326 ``/fork-remote``
 327   Fork a remote URL
 328 ``/help``
 329   Show help page
 330 ``/new``
 331   Shows form for new paste
 332 ``/login``
 333   Login page for protecting site
 334 ``/setup``
 335   Check if everything is setup correctly and all dependencies are installed
 336 ``/user``
 337   Edit logged-in user information
 338
 339
 340 Internal directory layout
 341 =========================
 342 ::
 343
 344   repos/
 345     work/
 346       1/ - work directory for paste #1
 347       2/ - work directory for paste #2
 348     git/
 349       1.git/ - git repository for paste #1
 350         description - Description for the repository
 351       2.git/ - git repository for paste #2
 352
 353 nginx rewrites
 354 ==============
 355 If you use nginx, place the following lines into your ``server`` block:
 356
 357 ::
 358
 359   if (!-e $request_uri) {
 360     rewrite ^/([0-9]+)$ /display.php?id=$1;
 361     rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
 362     rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
 363     rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
 364     rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
 365     rewrite ^/([0-9]+)/edit/(.+)$ edit.php?id=$1&file=$2
 366     rewrite ^/([0-9]+)/embed$ /embed.php?id=$1;
 367     rewrite ^/([0-9]+)/embed/(.+)$ embed.php?id=$1&file=$2
 368     rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
 369     rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
 370     rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
 371     rewrite ^/([0-9]+)/rev-raw/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
 372     rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
 373
 374     rewrite ^/fork-remote$ /fork-remote.php;
 375     rewrite ^/help$ /help.php;
 376     rewrite ^/new$ /new.php;
 377
 378     rewrite ^/feed/new$ /feed-new.php;
 379     rewrite ^/feed/updated$ /feed-updated.php;
 380
 381     rewrite ^/list$ /list.php;
 382     rewrite ^/list/([0-9]+)$ /list.php?page=$1;
 383
 384     rewrite ^/search$ /search.php;
 385     rewrite ^/search/([0-9]+)$ /search.php?page=$1;
 386
 387     rewrite ^/login$ /login.php;
 388     rewrite ^/setup$ /setup.php;
 389     rewrite ^/user$ /user.php;
 390   }