README.rst - Updated for OpenID instructions

[phorkie.git] / README.rst

diff --git a/README.rst b/README.rst
index 2485bbd56d3790ad59fe78a7c67802ad4a73a7a4..96a385374056f0a1065de142801f2382608634d8 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -11,28 +11,24 @@ Project page: http://sourceforge.net/p/phorkie/
 ========
 Features
 ========
 ========
 Features
 ========

-- every paste is a git repository
-
+  - every paste is a git repository

   - repositories can be cloned
   - clone url can be displayed
   - repositories can be cloned
   - clone url can be displayed

-- paste editing
-
+  - openid authentication
+  - paste editing

   - add new files
   - delete existing files
   - replace file with upload
   - add new files
   - delete existing files
   - replace file with upload

-- multiple files in one paste
-- syntax highlighting with GeSHi
-- rST rendering
-- image upload + display
-- external tool support
-
+  - multiple files in one paste
+  - syntax highlighting with GeSHi
+  - rST and Markdown rendering
+  - image upload + display
+  - external tool support

   - xmllint
   - php syntax check
   - xmllint
   - php syntax check

-- history in the sidebar
-
+  - history in the sidebar

   - old files can be downloaded easily
   - 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
 
 
   - options: quoting, logical and, or, not, partial words
 
 


@@ -56,22 +52,23 @@ Installation
    $ cp data/config.php.dist data/config.php
    $ $EDITOR data/config.php
 
    $ cp data/config.php.dist data/config.php
    $ $EDITOR data/config.php
 

-5. Set your web server's document root to ``/path/to/phorkie-0.2.0/www/``
+   Look at ``config.default.php`` for values that you may adjust.
+
+5. Set your web server's document root to ``/path/to/phorkie/www/``

 
 6. Open phorkie in your web browser
 
 
 Dependencies
 ============
 
 6. Open phorkie in your web browser
 
 
 Dependencies
 ============

-phorkie stands on the shoulders of giants.
-
+phorkie stands on the shoulders of giants.  Git will need to be a
+minimum version of v1.7.4.

 ::
 ::

-

   $ pear install versioncontrol_git-alpha
   $ pear install services_libravatar-alpha
   $ pear install http_request2
   $ pear install pager
   $ pear install versioncontrol_git-alpha
   $ pear install services_libravatar-alpha
   $ pear install http_request2
   $ pear install pager

-  $ pear install https://github.com/downloads/cweiske/Date_HumanDiff/Date_HumanDiff-0.1.0.tgz
+  $ pear install date_humandiff-alpha

 
   $ pear channel-discover pear.twig-project.org
   $ pear install twig/Twig
 
   $ pear channel-discover pear.twig-project.org
   $ pear install twig/Twig


@@ -79,15 +76,21 @@ phorkie stands on the shoulders of giants.
   $ pear channel-discover mediawiki.googlecode.com/svn
   $ pear install mediawiki/geshi
 
   $ pear channel-discover mediawiki.googlecode.com/svn
   $ pear install mediawiki/geshi
 

-Note that this version of GeSHi is a bit outdated, but it's the fastest
-way to install it.
+  $ 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``.

 
 ======
 Search
 ======
 
 
 ======
 Search
 ======
 

-phorkie makes use of an Elasticsearch__ installation if you have one.
+phorkie makes use of an Elasticsearch__ installation, if you have one.

 
 It is used to provide search capabilities and the list of recent pastes.
 
 
 It is used to provide search capabilities and the list of recent pastes.
 


@@ -108,6 +111,18 @@ That's all. Open phorkie in your browser, and you'll notice the search box
 in the top menu.
 
 
 in the top menu.
 
 

+Reset
+=====
+In case something really went wrong and you need to reset the search
+index, run the following command::
+
+  $ curl -XDELETE http://localhost:9200/phorkie/
+  {"ok":true,"acknowledged"}
+
+Phorkie will automatically re-index everything when ``setupcheck`` is enabled
+in the configuration file.
+
+

 =====
 HowTo
 =====
 =====
 HowTo
 =====


@@ -127,9 +142,21 @@ Edit your ``config.php`` and set the ``$GLOBALS['phorkie']['cfg']['git']['public
 setting to ``git://$yourhostname/git/paste/``.
 The rest will be appended automatically.
 
 setting to ``git://$yourhostname/git/paste/``.
 The rest will be appended automatically.
 

-

 You're on your own to setup writable repositories.
 
 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.default.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
+``$GLOBALS['phorkie']['auth']['users']`` variable.
+

 
 =================
 Technical details
 
 =================
 Technical details


@@ -137,7 +164,6 @@ Technical details
 
 TODO
 ====
 
 TODO
 ====

-- OpenID-Login to get username+email as authorship information

 - filters (``xmllint --format``, ``rapper``)
 - document how to keep disk usage low (block size)
 - comments
 - filters (``xmllint --format``, ``rapper``)
 - document how to keep disk usage low (block size)
 - comments


@@ -152,7 +178,7 @@ URLs
 ====
 
 ``/``
 ====
 
 ``/``

-  Index page. Shows form for new paste
+  Index page.

 ``/[0-9]+``
   Display page for paste
 ``/[0-9]/edit``
 ``/[0-9]+``
   Display page for paste
 ``/[0-9]/edit``


@@ -165,12 +191,20 @@ URLs
   Show specific revision of the paste
 ``/[0-9]/delete``
   Delete the paste
   Show specific revision of the paste
 ``/[0-9]/delete``
   Delete the paste

+``/[0-9]/doap``
+  Show DOAP document for paste

 ``/[0-9]/fork``
   Create a fork of the paste
 ``/search?q=..(&page=[0-9]+)?``
   Search for term, with optional page
 ``/list(/[0-9])?``
   List all pastes, with optional page
 ``/[0-9]/fork``
   Create a fork of the paste
 ``/search?q=..(&page=[0-9]+)?``
   Search for term, with optional page
 ``/list(/[0-9])?``
   List all pastes, with optional page

+``/new``
+  Shows form for new paste
+``/login``
+  Login page for protecting site
+``/user``
+  Edit logged-in user information

 
 
 Internal directory layout
 
 
 Internal directory layout


@@ -185,3 +219,32 @@ Internal directory layout
       1.git/ - git repository for paste #1
         description - Description for the repository
       2.git/ - git repository for paste #2
       1.git/ - git repository for paste #1
         description - Description for the repository
       2.git/ - git repository for paste #2

+
+nginx rewrites
+==============
+If you use nginx, place the following lines into your ``server`` block:
+
+::
+
+  if (!-e $request_uri) {
+    rewrite ^/([0-9]+)$ /display.php?id=$1;
+    rewrite ^/([0-9]+)/delete$ /delete.php?id=$1;
+    rewrite ^/([0-9]+)/delete/confirm$ /delete.php?id=$1&confirm=1;
+    rewrite ^/([0-9]+)/doap$ /doap.php?id=$1;
+    rewrite ^/([0-9]+)/edit$ /edit.php?id=$1;
+    rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
+    rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
+    rewrite ^/([0-9]+)/rev/(.+)$ /revision.php?id=$1&rev=$2;
+    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 ^/new$ /new.php;
+    rewrite ^/list$ /list.php;
+    rewrite ^/list/([0-9]+)$ /list.php?page=$1;
+
+    rewrite ^/search$ /search.php;
+    rewrite ^/search/([0-9]+)$ /search.php?page=$1;
+
+    rewrite ^/login$ /login.php;
+    rewrite ^/user$ /user.php;
+  }