git.cweiske.de / phorkie.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
update readme
[phorkie.git] / README.rst
diff --git a/README.rst b/README.rst
index 56bef951efa6c46a0bcf4013c4775dbb43f102fb..ee2f7e8095a37e9c2430c11b0d0305282bb4fbfb 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -15,6 +15,7 @@ Features
 
   - repositories can be cloned
   - clone url can be displayed
 
   - 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
 - paste editing
 
   - add new files
@@ -22,8 +23,9 @@ Features
   - replace file with upload
 - multiple files in one paste
 - syntax highlighting with GeSHi
   - replace file with upload
 - multiple files in one paste
 - syntax highlighting with GeSHi
-- rST rendering
+- rST and Markdown rendering
 - image upload + display
 - image upload + display
+- OpenID authentication
 - external tool support
 
   - xmllint
 - external tool support
 
   - xmllint
@@ -41,7 +43,7 @@ Installation
 ============
 1. Unzip the phorkie release file::
 
 ============
 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::
 
 
 2. Create the git directories::
 
@@ -58,7 +60,7 @@ Installation
 
    Look at ``config.default.php`` for values that you may adjust.
 
 
    Look at ``config.default.php`` for values that you may adjust.
 
-5. Set your web server's document root to ``/path/to/phorkie-0.2.0/www/``
+5. Set your web server's document root to ``/path/to/phorkie/www/``
 
 6. Open phorkie in your web browser
 
 
 6. Open phorkie in your web browser
 
@@ -67,6 +69,13 @@ Dependencies
 ============
 phorkie stands on the shoulders of giants.
 
 ============
 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 versioncontrol_git-alpha
@@ -84,15 +93,20 @@ phorkie stands on the shoulders of giants.
   $ pear channel-discover zustellzentrum.cweiske.de
   $ pear install zz/mime_type_plaindetect-alpha
 
   $ 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.
 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``.
 
 
 ======
 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.
 
@@ -124,6 +138,10 @@ index, run the following command::
 Phorkie will automatically re-index everything when ``setupcheck`` is enabled
 in the configuration file.
 
 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
 
 =====
 HowTo
@@ -134,7 +152,7 @@ Make git repositories clonable
 To make git repositories clonable, you need to install ``git-daemon``
 (``git-daemon-run`` package on Debian/Ubuntu).
 
 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.::
 
 directory (``$GLOBALS['phorkie']['cfg']['repos']`` setting) into
 ``/var/cache/git``, e.g.::
 
@@ -148,13 +166,46 @@ 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.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/
+
+
 =================
 Technical details
 =================
 
 TODO
 ====
 =================
 Technical details
 =================
 
 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
@@ -182,6 +233,8 @@ 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]+)?``
 ``/[0-9]/fork``
   Create a fork of the paste
 ``/search?q=..(&page=[0-9]+)?``
@@ -192,10 +245,6 @@ URLs
   Shows form for new paste
 ``/login``
   Login page for protecting site
   Shows form for new paste
 ``/login``
   Login page for protecting site
-``/auth``
-  Authentication callback url
-``/forbidden``
-  Access denied page
 ``/user``
   Edit logged-in user information
 
 ``/user``
   Edit logged-in user information
 
@@ -223,6 +272,7 @@ If you use nginx, place the following lines into your ``server`` block:
     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]+)$ /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]+)/edit$ /edit.php?id=$1;
     rewrite ^/([0-9]+)/fork$ /fork.php?id=$1;
     rewrite ^/([0-9]+)/raw/(.+)$ /raw.php?id=$1&file=$2;
@@ -238,7 +288,5 @@ 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 ^/search/([0-9]+)$ /search.php?page=$1;
 
     rewrite ^/login$ /login.php;
-    rewrite ^/auth$ /auth.php;
-    rewrite ^/forbidden$ /forbidden.php;
     rewrite ^/user$ /user.php;
   }
     rewrite ^/user$ /user.php;
   }
Self-hosted pastebin software written in PHP. Pastes are editable, may have multiple files and are stored in git repositories.