X-Git-Url: https://git.cweiske.de/phorkie.git/blobdiff_plain/6c0d5be1b6ec69257b09b97ddfe0405eabe92459..f47ddf0758f120dfb26f03fb36be5cd897a10f23:/README.rst diff --git a/README.rst b/README.rst index e7e1625..f70796a 100644 --- a/README.rst +++ b/README.rst @@ -15,16 +15,17 @@ Features - repositories can be cloned - clone url can be displayed + - remote pastes can be forked (rel="vcs-git" and gist.github.com) - paste editing - add new files - delete existing files - replace file with upload -- OpenID authentication - multiple files in one paste - syntax highlighting with GeSHi - rST and Markdown rendering - image upload + display +- OpenID authentication - external tool support - xmllint @@ -35,6 +36,7 @@ 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 ============ @@ -60,6 +62,12 @@ 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 @@ -68,9 +76,12 @@ Dependencies ============ phorkie stands on the shoulders of giants. -- git v1.7.5 -- php v5.3.0 -- pear v1.9.2 +It requires the following programs to be installed +on your machine: + +- Git v1.7.5 or later +- PHP v5.3.0 or later +- PEAR v1.9.2 or later :: @@ -79,6 +90,7 @@ phorkie stands on the shoulders of giants. $ 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 @@ -91,10 +103,12 @@ phorkie stands on the shoulders of giants. $ 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 in ``data/config.default.php``. +way to install it. +If you install it manually be sure to update the +path from ``data/config.default.php``. + ====== Search @@ -106,6 +120,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 @@ -113,6 +128,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 @@ -132,6 +148,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 @@ -152,22 +172,75 @@ Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public setting to ``git://$yourhostname/git/paste/``. The rest will be appended automatically. + You're on your own to setup writable repositories. + Protect your site with OpenID ============================= You have the option of enabling OpenID authentication to help secure your -pastes on phorkie. Set the ``$GLOBALS['phorkie']['auth']`` values in the -``data/config.php`` file as desired. - -There are two different types of security you can apply. First, you can -restrict to one of three ``securityLevels``; completely open (``0``), protection -of write-enabled functions such as add, edit, etc. (``1``), and full site -protection (``2``). Additionally, you can restrict your site to ``listedUsersOnly``. -You will need to add the individual OpenIDs identity urls to the +pastes on phorkie. +Set the ``$GLOBALS['phorkie']['auth']`` values in the +``data/config.php`` file as desired. + +There are two different types of security you can apply. +First, you can restrict to one of three ``securityLevels``: + +- completely open (``0``) +- protection of write-enabled functions such as add, edit, etc. (``1``) +- full site protection (``2``) + +Additionally, you can restrict your site to ``listedUsersOnly``. +You will need to add the individual OpenID urls to the ``$GLOBALS['phorkie']['auth']['users']`` variable. +Get information about paste editors +=================================== +Phorkie stores the user's OpenID or IP address (when not logged in) when +a paste is edited. +It is possible to get this information for each single commit:: + + // IP / OpenID for the latest commit + $ git notes --ref=identity show + 127.0.0.1 + + // show IP / OpenID for a given commit + $ git notes --ref=identity show 29f82a + 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 ================= @@ -249,6 +322,8 @@ If you use nginx, place the following lines into your ``server`` block: rewrite ^/([0-9]+)/tool/([^/]+)/(.+)$ /tool.php?id=$1&tool=$2&file=$3; 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;