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