X-Git-Url: https://git.cweiske.de/phorkie.git/blobdiff_plain/3830eb9255c04f0483736eb9f5167a411da325f5..f47ddf0758f120dfb26f03fb36be5cd897a10f23:/README.rst diff --git a/README.rst b/README.rst index a6660fb..f70796a 100644 --- a/README.rst +++ b/README.rst @@ -11,25 +11,32 @@ Project page: http://sourceforge.net/p/phorkie/ ======== Features ======== - - every paste is a git repository +- every paste is a git repository + - repositories can be cloned - clone url can be displayed - - openid authentication - - paste editing + - remote pastes can be forked (rel="vcs-git" and gist.github.com) +- paste editing + - add new files - delete existing files - replace file with upload - - multiple files in one paste - - syntax highlighting with GeSHi - - rST and Markdown rendering - - image upload + display - - external tool support +- multiple files in one paste +- syntax highlighting with GeSHi +- rST and Markdown rendering +- image upload + display +- OpenID authentication +- external tool support + - xmllint - php syntax check - - history in the sidebar +- history in the sidebar + - old files can be downloaded easily - - search across pastes: description, file names and file content +- 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 ============ @@ -37,7 +44,7 @@ Installation ============ 1. Unzip the phorkie release file:: - $ tar xjvf phorkie-0.2.0.tar.bz2 + $ tar xjvf phorkie-0.3.0.tar.bz2 2. Create the git directories:: @@ -55,20 +62,35 @@ 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 Dependencies ============ -phorkie stands on the shoulders of giants. Git will need to be a -minimum version of v1.7.4. +phorkie stands on the shoulders of giants. + +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 + :: + $ pear install versioncontrol_git-alpha $ pear install services_libravatar-alpha $ 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 @@ -81,10 +103,12 @@ minimum version of v1.7.4. $ 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 @@ -96,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 @@ -103,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 @@ -122,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 @@ -132,7 +162,7 @@ Make git repositories clonable To make git repositories clonable, you need to install ``git-daemon`` (``git-daemon-run`` package on Debian/Ubuntu). -Now make the repositories available by symlinking the paste repository +Make the repositories available by symlinking the paste repository directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into ``/var/cache/git``, e.g.:: @@ -142,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. 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 ================= @@ -239,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;