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