README.rst

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