X-Git-Url: https://git.cweiske.de/phorkie.git/blobdiff_plain/3830eb9255c04f0483736eb9f5167a411da325f5..43b23197ffc3e1d08a1e08b09dbb31f06692d7ff:/README.rst diff --git a/README.rst b/README.rst index a6660fb..043c438 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,36 +62,54 @@ 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 http://yourhost/setup in your web browser to see if everything + is working fine. -6. Open phorkie in your web browser +7. Go to http://yourhost/ 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 - $ 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 $ 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``. + + $ pear channel-discover pear2.php.net + $ pear install pear2/pear2_services_linkback-alpha + ====== Search @@ -96,6 +121,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 +129,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 +149,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 +163,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 +173,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 ================= @@ -199,10 +283,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 @@ -238,7 +328,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; @@ -246,5 +340,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; }