X-Git-Url: https://git.cweiske.de/phorkie.git/blobdiff_plain/6d769643d342032c06bc6fe00c7864b81c423bac..abf08ecdb046202de8b5abf0392b4b76a5d0f89a:/README.rst diff --git a/README.rst b/README.rst index a11d327..a755d3a 100644 --- a/README.rst +++ b/README.rst @@ -16,6 +16,7 @@ Features - repositories can be cloned - clone url can be displayed - remote pastes can be forked (rel="vcs-git" and gist.github.com) + - single click forking of forks on different servers to your own - paste editing - add new files @@ -36,19 +37,42 @@ Features - search across pastes: description, file names and file content - options: quoting, logical and, or, not, partial words +- webhook support - get notified when pastes are created, edited or deleted +- atom feed for new and updated pastes +- notifies remote instances via linkbacks when a paste has been forked ============ Installation ============ + +.phar +===== +Download ``phorkie-0.4.0.phar`` and put it in your web server's document root +directory. + +No further setup needed. + +.. note:: Only valid if your webserver is configured to let + PHP handle ``.phar`` files. + + Unfortunately, no Linux distribution has this activated by default. + +.. warning:: PHP has some bugs in its .phar handling code (e.g. with FPM). + + So currently, the ``.phar`` option is considered experimental. + + +Zip package +=========== 1. Unzip the phorkie release file:: - $ tar xjvf phorkie-0.3.0.tar.bz2 + $ tar xjvf phorkie-0.4.0.tar.bz2 2. Create the git directories:: - $ mkdir -p repos/git repos/work - $ chmod og+w repos/git repos/work + $ mkdir -p www/repos/git www/repos/work + $ chmod og+w www/repos/git www/repos/work 3. Install dependencies_ @@ -61,8 +85,17 @@ Installation Look at ``config.default.php`` for values that you may adjust. 5. Set your web server's document root to ``/path/to/phorkie/www/`` + Alternatively, you can add a symlink to the ``www`` folder into your + web server's existing document root tree (being careful to keep + main phorkie folder outside the document root for security purposes) + and ensure you set the ``baseurl`` config option appropriately. You + must also set the ``RewriteBase`` in the ``.htaccess`` file or adjust + the nginx configuration accordingly. -6. Open phorkie in your web browser +6. Open http://yourhost/setup in your web browser to see if everything + is working fine. + +7. Go to http://yourhost/ Dependencies @@ -83,12 +116,13 @@ on your machine: $ pear install http_request2 $ pear install pager $ pear install date_humandiff-alpha + $ pear install openid-alpha $ pear channel-discover pear.twig-project.org $ pear install twig/Twig - $ pear channel-discover mediawiki.googlecode.com/svn - $ pear install mediawiki/geshi + $ pear channel-discover pear.geshi.org + $ pear install geshi/geshi $ pear channel-discover zustellzentrum.cweiske.de $ pear install zz/mime_type_plaindetect-alpha @@ -96,10 +130,16 @@ on your machine: $ pear channel-discover pear.michelf.ca $ pear install michelf/Markdown -Note that this version of GeSHi is a bit outdated, but it's the fastest -way to install it. -If you install it manually be sure to update the -path from ``data/config.default.php``. + $ pear channel-discover pear2.php.net + $ pear install pear2/pear2_services_linkback-alpha + + +You can use composer to install all dependencies automatically:: + + $ composer install + +Note that the ``.phar`` package already contains all dependencies. + ====== Search @@ -111,6 +151,7 @@ It is used to provide search capabilities and the list of recent pastes. __ http://www.elasticsearch.org/ + Setup ===== Edit ``config.php``, setting the ``elasticsearch`` property to the HTTP URL @@ -118,6 +159,7 @@ of the index, e.g. :: http://localhost:9200/phorkie/ +You must use a search namespace with Elasticsearch such as ``phorkie/``. Run the index script to import all existing pastes into the index:: php scripts/index.php @@ -137,6 +179,10 @@ index, run the following command:: Phorkie will automatically re-index everything when ``setupcheck`` is enabled in the configuration file. +You may also manually run the reindexing script with:: + + $ php scripts/index.php + ===== HowTo @@ -144,8 +190,19 @@ HowTo Make git repositories clonable ============================== -To make git repositories clonable, you need to install ``git-daemon`` -(``git-daemon-run`` package on Debian/Ubuntu). + +HTTP +---- +By default, the pastes are clonable via ``http`` as long as the ``repos/git/`` +directory is within the ``www/`` directory. + +No further setup needed. + + +git-daemon +---------- +You may use ``git-daemon`` to provide public ``git://`` clone urls. +Install the ``git-daemon-run`` package on Debian/Ubuntu. Make the repositories available by symlinking the paste repository directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into @@ -195,21 +252,41 @@ It is possible to get this information for each single commit:: http://cweiske.de/ +Notifications via webhooks +========================== +Depending on how you use phorkie, it might be nice to notify some other service +when pastes are added or updated. +Phorkie contains a simply mechanism to post data to a given URL which +you can then use as needed. + +The data are json-encoded POSTed to the URLs contained in the +``$GLOBALS['phorkie']['cfg']['webhooks']`` setting array, with +a MIME type of ``application/vnd.phorkie.webhook+json``:: + + { + 'event': 'create', + 'author': { + 'name':'Anonymous', + 'email': 'anonymous@phorkie', + }, + 'repository': { + 'name': 'webhooktest', + 'url': 'http://example.org/33', + 'description': 'webhooktest', + 'owner': { + 'name': 'Anonymous', + 'email': 'anonymous@phorkie', + } + } + } + +The event may be ``create``, ``edit`` or ``delete``. + + ================= Technical details ================= -TODO -==== -- filters (``xmllint --format``, ``rapper``) -- document how to keep disk usage low (block size) -- comments -- when 2 people edit, merge changes -- diff changes -- configurable highlights -- Atom feed for new pastes -- Atom feed for paste changes - URLs ==== @@ -236,10 +313,16 @@ URLs Search for term, with optional page ``/list(/[0-9])?`` List all pastes, with optional page +``/fork-remote`` + Fork a remote URL +``/help`` + Show help page ``/new`` Shows form for new paste ``/login`` Login page for protecting site +``/setup`` + Check if everything is setup correctly and all dependencies are installed ``/user`` Edit logged-in user information @@ -275,7 +358,11 @@ If you use nginx, place the following lines into your ``server`` block: rewrite ^/([0-9]+)/rev-raw/(.+)$ /raw.php?id=$1&rev=$2&file=$3; rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3; + rewrite ^/fork-remote$ /fork-remote.php; + rewrite ^/help$ /help.php; rewrite ^/new$ /new.php; + rewrite ^/feed/new$ /feed-new.php; + rewrite ^/feed/updated$ /feed-updated.php; rewrite ^/list$ /list.php; rewrite ^/list/([0-9]+)$ /list.php?page=$1; @@ -283,5 +370,6 @@ If you use nginx, place the following lines into your ``server`` block: rewrite ^/search/([0-9]+)$ /search.php?page=$1; rewrite ^/login$ /login.php; + rewrite ^/setup$ /setup.php; rewrite ^/user$ /user.php; }