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