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.6.1.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    You can do it yourself, though - see
  63    `Enable .phar handling in your web server`__.
  64
  65 .. warning:: PHP has some bugs in its .phar handling code (e.g. with FPM).
  66
  67    So currently, the ``.phar`` option is considered experimental.
  68
  69 __ http://cweiske.de/tagebuch/phar-webserver.htm
  70
  71
  72 Zip package
  73 ===========
  74 1. Unzip the phorkie release file::
  75
  76    $ tar xjvf phorkie-0.6.1.tar.bz2
  77
  78 2. Create the git directories::
  79
  80    $ mkdir -p www/repos/git www/repos/work
  81    $ chmod og+w www/repos/git www/repos/work
  82
  83 3. Install dependencies_
  84
  85 4. Copy ``data/config.php.dist`` to ``data/config.php`` and adjust it
  86    to your needs::
  87
  88    $ cp data/config.php.dist data/config.php
  89    $ $EDITOR data/config.php
  90
  91    Look at ``config.default.php`` for values that you may adjust.
  92
  93 5. Set your web server's document root to ``/path/to/phorkie/www/``
  94    Alternatively, you can add a symlink to the ``www`` folder into your
  95    web server's existing document root tree (being careful to keep
  96    main phorkie folder outside the document root for security purposes)
  97    and ensure you set the ``baseurl`` config option appropriately. You
  98    must also set the ``RewriteBase`` in the ``.htaccess`` file or adjust
  99    the nginx configuration accordingly.
 100
 101 6. Open http://yourhost/setup in your web browser to see if everything
 102    is working fine.
 103
 104 7. Go to http://yourhost/
 105
 106 8. If you like phorkie, send a mail to `cweiske+phorkie@cweiske.de`__
 107
 108 __ mailto:cweiske+phorkie@cweiske.de
 109
 110
 111 Dependencies
 112 ============
 113 phorkie stands on the shoulders of giants.
 114
 115 It requires the following programs to be installed
 116 on your machine:
 117
 118 - Git v1.7.5 or later
 119 - PHP v5.3.0 or later
 120 - PEAR v1.9.2 or later
 121
 122 ::
 123
 124   $ pear install versioncontrol_git-alpha
 125   $ pear install services_libravatar-alpha
 126   $ pear install http_request2
 127   $ pear install pager
 128   $ pear install date_humandiff-alpha
 129   $ pear install openid-alpha
 130
 131   $ pear channel-discover pear.twig-project.org
 132   $ pear install twig/Twig
 133
 134   $ pear channel-discover pear.geshi.org
 135   $ pear install geshi/geshi
 136
 137   $ pear channel-discover zustellzentrum.cweiske.de
 138   $ pear install zz/mime_type_plaindetect-alpha
 139
 140   $ pear channel-discover pear.michelf.ca
 141   $ pear install michelf/Markdown
 142
 143   $ pear channel-discover pear2.php.net
 144   $ pear install pear2/pear2_services_linkback-alpha
 145
 146
 147 You can use composer to install all dependencies automatically::
 148
 149   $ composer install
 150
 151 Note that the ``.phar`` package already contains all dependencies.
 152
 153
 154 ======
 155 Search
 156 ======
 157
 158 phorkie makes use of an Elasticsearch__ installation, if you have one.
 159
 160 It is used to provide search capabilities and the list of recent pastes.
 161
 162 Elasticsearch version 2.0 is supported.
 163
 164 You have to install the `delete-by-query`__ plugin::
 165
 166     $ cd /usr/share/elasticsearch
 167     $ bin/plugin install delete-by-query
 168
 169 __ http://www.elasticsearch.org/
 170 __ https://www.elastic.co/guide/en/elasticsearch/plugins/2.0/plugins-delete-by-query.html
 171
 172
 173 Setup
 174 =====
 175 Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL
 176 of the index, e.g. ::
 177
 178   http://localhost:9200/phorkie/
 179
 180 You must use a search namespace with Elasticsearch such as ``phorkie/``.
 181 Run the index script to import all existing pastes into the index::
 182
 183   php scripts/index.php
 184
 185 That's all. Open phorkie in your browser, and you'll notice the search box
 186 in the top menu.
 187
 188
 189 Reset
 190 =====
 191 In case something really went wrong and you need to reset the search
 192 index, run the following command::
 193
 194   $ curl -XDELETE http://localhost:9200/phorkie/
 195   {"ok":true,"acknowledged"}
 196
 197 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
 198 in the configuration file.
 199
 200 You may also manually run the reindexing script with::
 201
 202   $ php scripts/index.php
 203
 204
 205 =====
 206 HowTo
 207 =====
 208
 209 Make git repositories clonable
 210 ==============================
 211
 212 HTTP
 213 ----
 214 By default, the pastes are clonable via ``http`` as long as the ``repos/git/``
 215 directory is within the ``www/`` directory.
 216
 217 No further setup needed.
 218
 219
 220 git-daemon
 221 ----------
 222 You may use ``git-daemon`` to provide public ``git://`` clone urls.
 223 Install the ``git-daemon-run`` package on Debian/Ubuntu.
 224
 225 Make the repositories available by symlinking the paste repository
 226 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
 227 ``/var/cache/git``, e.g.::
 228
 229   $ ln -s /home/user/www/paste/repos/git /var/cache/git/paste
 230
 231 Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public']``
 232 setting to ``git://$yourhostname/git/paste/``.
 233 The rest will be appended automatically.
 234
 235
 236 You're on your own to setup writable repositories.
 237
 238
 239 Protect your site with OpenID
 240 =============================
 241 You have the option of enabling OpenID authentication to help secure your
 242 pastes on phorkie.
 243 Set the ``$GLOBALS['phorkie']['auth']`` values in the
 244 ``data/config.php`` file as desired.
 245
 246 There are two different types of security you can apply.
 247 First, you can restrict to one of three ``securityLevels``:
 248
 249 - completely open (``0``)
 250 - protection of write-enabled functions such as add, edit, etc. (``1``)
 251 - full site protection (``2``)
 252
 253 Additionally, you can restrict your site to ``listedUsersOnly``.
 254 You will need to add the individual OpenID urls to the
 255 ``$GLOBALS['phorkie']['auth']['users']`` variable.
 256
 257
 258 Get information about paste editors
 259 ===================================
 260 Phorkie stores the user's OpenID or IP address (when not logged in) when
 261 a paste is edited.
 262 It is possible to get this information for each single commit::
 263
 264     // IP / OpenID for the latest commit
 265     $ git notes --ref=identity show
 266     127.0.0.1
 267
 268     // show IP / OpenID for a given commit
 269     $ git notes --ref=identity show 29f82a
 270     http://cweiske.de/
 271
 272
 273 Notifications via webhooks
 274 ==========================
 275 Depending on how you use phorkie, it might be nice to notify some other service
 276 when pastes are added or updated.
 277 Phorkie contains a simply mechanism to post data to a given URL which
 278 you can then use as needed.
 279
 280 The data are json-encoded POSTed to the URLs contained in the
 281 ``$GLOBALS['phorkie']['cfg']['webhooks']`` setting array, with
 282 a MIME type of ``application/vnd.phorkie.webhook+json``::
 283
 284   {
 285       'event': 'create',
 286       'author': {
 287           'name':'Anonymous',
 288           'email': 'anonymous@phorkie',
 289       },
 290       'repository': {
 291           'name': 'webhooktest',
 292           'url': 'http://example.org/33',
 293           'description': 'webhooktest',
 294           'owner': {
 295               'name': 'Anonymous',
 296               'email': 'anonymous@phorkie',
 297           }
 298       }
 299   }
 300
 301 The event may be ``create``, ``edit`` or ``delete``.
 302
 303
 304 =================
 305 Technical details
 306 =================
 307
 308
 309 URLs
 310 ====
 311
 312 ``/``
 313   Index page.
 314 ``/[0-9]+``
 315   Display page for paste
 316 ``/[0-9]+/edit``
 317   Edit the paste
 318 ``/[0-9]+/edit/(.+)``
 319   Edit a single file of the paste
 320 ``/[0-9]+/embed``
 321   JavaScript code that embeds the whole paste in a HTML page
 322 ``/[0-9]+/embed/(.+)``
 323   JavaScript code that embeds a single file in a HTML page
 324 ``/[0-9]+/raw/(.+)``
 325   Display raw file contents
 326 ``/[0-9]+/tool/[a-zA-Z]+/(.+)``
 327   Run a tool on the given file
 328 ``/[0-9]+/rev/[a-z0-9]+``
 329   Show specific revision of the paste
 330 ``/[0-9]+/delete``
 331   Delete the paste
 332 ``/[0-9]+/doap``
 333   Show DOAP document for paste
 334 ``/[0-9]+/fork``
 335   Create a fork of the paste
 336 ``/search?q=..(&page=[0-9]+)?``
 337   Search for term, with optional page
 338 ``/list(/[0-9]+)?``
 339   List all pastes, with optional page
 340 ``/fork-remote``
 341   Fork a remote URL
 342 ``/help``
 343   Show help page
 344 ``/new``
 345   Shows form for new paste
 346 ``/login``
 347   Login page for protecting site
 348 ``/setup``
 349   Check if everything is setup correctly and all dependencies are installed
 350 ``/user``
 351   Edit logged-in user information
 352
 353
 354 Internal directory layout
 355 =========================
 356 ::
 357
 358   repos/
 359     work/
 360       1/ - work directory for paste #1
 361       2/ - work directory for paste #2
 362     git/
 363       1.git/ - git repository for paste #1
 364         description - Description for the repository
 365       2.git/ - git repository for paste #2
 366
 367 nginx rewrites
 368 ==============
 369 If you use nginx, place the following lines into your ``server`` block:
 370
 371 ::
 372
 373   if (!-e $request_uri) {
 374     rewrite ^/([0-9]+)$ /display.php?id=$1;
 375     rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
 376     rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
 377     rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
 378     rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
 379     rewrite ^/([0-9]+)/edit/(.+)$ /edit.php?id=$1&file=$2;
 380     rewrite ^/([0-9]+)/embed$ /embed.php?id=$1;
 381     rewrite ^/([0-9]+)/embed/(.+)$ /embed.php?id=$1&file=$2;
 382     rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
 383     rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
 384     rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
 385     rewrite ^/([0-9]+)/rev-raw/(.+)/(.+)$ /raw.php?id=$1&rev=$2&file=$3;
 386     rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3;
 387
 388     rewrite ^/fork-remote$ /fork-remote.php;
 389     rewrite ^/help$ /help.php;
 390     rewrite ^/new$ /new.php;
 391
 392     rewrite ^/feed/new$ /feed-new.php;
 393     rewrite ^/feed/updated$ /feed-updated.php;
 394
 395     rewrite ^/list$ /list.php;
 396     rewrite ^/list/([0-9]+)$ /list.php?page=$1;
 397
 398     rewrite ^/search$ /search.php;
 399     rewrite ^/search/([0-9]+)$ /search.php?page=$1;
 400
 401     rewrite ^/login$ /login.php;
 402     rewrite ^/setup$ /setup.php;
 403     rewrite ^/user$ /user.php;
 404   }
 405
 406 Lighttpd rewrites
 407 =================
 408
 409 ::
 410
 411     url.rewrite-once += (
 412         "^/([0-9]+)$" => "/display.php?id=$1",
 413         "^/([0-9]+)/delete$" => "/delete.php?id=$1",
 414         "^/([0-9]+)/delete/confirm" => "/delete.php?&id=$1&confirm=1",
 415         "^/([0-9]+)/doap$" => "/doap.php?id=$1",
 416         "^/([0-9]+)/edit$" => "/edit.php?id=$1",
 417         "^/([0-9]+)/edit/(.+)" => "/edit.php?id=$1&file=$2",
 418         "^/([0-9]+)/embed$" => "/embed.php?id=$1",
 419         "^/([0-9]+)/embed/(.+)$" => "/embed.php?id=$1",
 420         "^/([0-9]+)/fork$" => "/fork.php?id=$1",
 421         "^/([0-9]+)/raw/(.+)$" => "/raw.php?id=$1&file=$2",
 422         "^/([0-9]+)/rev/(.+)$" => "/revision.php?id=$1&rev=$2",
 423         "^/([0-9]+)/rev-raw/(.+)/(.+)$" => "/raw.php?id=$1&rev=$2&file=$3",
 424         "^/([0-9]+)/tool/([^/]+)/(.+)$" => "/tool.php?id=$1&tool=$2&file=$3",
 425
 426         "^/fork-remote$" => "/fork-remote.php",
 427         "^/help$" => "/help.php",
 428         "^/new$" => "/new.php",
 429
 430         "^/feed/new$" => "/feed-new.php",
 431         "^/feed/updated$" => "/feed-updated.php",
 432
 433         "^/list$" => "/list.php",
 434         "^/list/([0-9]+)$" => "/list.php?page=$1",
 435
 436         "^/search$" => "/search.php",
 437         "^/search/([0-9]+)$" => "/search.php?page=$1",
 438
 439         "^/login$" => "/login.php",
 440         "^/setup$" => "/setup.php",
 441         "^/user$" => "/user.php"
 442     )
 443
 444
 445 ===========
 446 Development
 447 ===========
 448
 449 Releasing a new version
 450 =======================
 451
 452 #. Update ``ChangeLog``, ``NEWS.rst``, ``build.xml`` and ``README.rst``.
 453 #. Update local dependencies::
 454
 455     $ phing collectdeps
 456 #. Build ``.tar.bz2`` and ``.phar`` release files with::
 457
 458     $ phing zip
 459     $ phing phar
 460 #. Test.
 461 #. Tag the release in git
 462 #. Upload release to sourceforge::
 463
 464     $ phing deploy-sf