1 files changed, 148 insertions, 0 deletions
diff --git a/doc/INSTALL.txt b/doc/INSTALL.txt
new file mode 100644
index 0000000..c911740
--- /dev/null
+++ b/doc/INSTALL.txt
@@ -0,0 +1,148 @@
+============================
+SemanticScuttle installation
+============================
+
+.. contents::
+
+Prerequisites
+=============
+To run SemanticScuttle, you need:
+
+- PHP5 with filter functions enabled
+- A web server, for example Apache
+
+
+Standard installation instructions
+==================================
+If you've downloaded a ``SemanticScuttle-x.y.z.zip`` file from SourceForge,
+then this instructions are for you.
+
+1. Create a new MySQL/PostgreSQL database
+2. Import ``data/tables.sql`` into that database, i.e.
+   run ::
+
+   $ mysql -umyusername -p mydatabasename < data/tables.sql
+
+   on the shell.
+
+   If you run PostgreSQL, use ``tables-postgresql.sql``::
+
+   $ psql mydatabasename myusername < data/tables-postgresql.sql
+
+3. Copy ``data/config.php.dist`` to ``data/config.php`` and modify it as
+   necessary. See configuration_ for more information.
+4. Make the cache directory writable by your web server.
+   For example, run ::
+
+   $ chmod 0777 cache
+
+   on the shell.
+5. Set the ``www/`` directory as document root in your web server,
+   restart the web server.
+6. That's all! Visit your SemanticScuttle installation web site now
+   with your browser.
+7. Register a user and add bookmarks.
+
+
+.. _configuration: configuration.html
+
+
+Ugly www directory in URLs
+--------------------------
+In case point 5 of the installation instructions cannot be put into
+practice by you because you are not able to change the web server
+configuration, you are not lost! There is a way to get rid of
+``www/`` in your URL!
+
+Imagine following directory layout: ::
+
+ /home/customer123/
+   www/
+     subdomain1/
+     subdomain2/
+     subdomain3/
+
+Create a SemanticScuttle directory somewhere outside ``www`` if possible
+and put all directories except ``www/`` in there. Move all files and
+directories from ``www/`` into your subdomain directory. Then modify
+``subdomain/www-header.php`` to include the correct file path.
+
+The new directory layout should look that way: ::
+
+ /home/customer123/
+   semanticscuttle/
+     doc/
+     data/
+     src/
+   www/
+     subdomain1/
+     subdomain2/ (this is the semanticscuttle subdomain)
+       about.php
+       admin.php
+       ..
+       www-header.php
+     subdomain3/
+
+Now open www-header.php and replace ::
+
+  require_once '../src/SemanticScuttle/header.php';
+
+with ::
+
+  require_once '../../semanticscuttle/src/SemanticScuttle/header.php';
+
+
+
+PEAR package installation
+=========================
+Apart from the normal installation, you may install the SemanticScuttle PEAR
+package - it gives you the ability to upgrade to the next version with a single
+command, without manually unzipping files.
+
+0. The SemanticScuttle PEAR channel is available at
+   http://semanticscuttle.sourceforge.net/pirum.html
+
+1. Make sure you have the PEAR installer (or Pyrus) available and working.
+   You can check that by running ::
+
+     $ pear version
+     PEAR Version: 1.9.2
+     PHP Version: 5.3.6-13ubuntu3.2
+     Zend Engine Version: 2.3.0
+     Running on: Linux bogo 3.0.0-12-generic #20-Ubuntu SMP Fri Oct 7 14:56:25 UTC 2011 x86_64
+
+2. Discover the channel if you haven't done so yet::
+
+     $ pear channel-discover semanticscuttle.sourceforge.net
+
+   Verify that the channel has been added with::
+
+     $ pear list-channels
+     Registered Channels:
+     ====================
+     Channel                         Alias     Summary
+     ...
+     semanticscuttle.sourceforge.net sc        SemanticScuttle PEAR channel
+     ...
+
+3. Install SemanticScuttle::
+
+     $ pear install sc/semanticscuttle-beta
+
+4. Find out where it got installed to::
+
+     $ pear list-files sc/semanticscuttle
+
+5. Generally, the directory you need to point your web server's ``DocumentRoot`` to
+   is the *PEAR www directory* + ``/SemanticScuttle/``. Find the www directory with::
+
+     $ pear config-get www_dir
+     /usr/share/php/htdocs
+
+6. The configuration file is located in *PEAR's data directory*  + ``/SemanticScuttle/``::
+
+     $ pear config-get data_dir
+     /usr/share/php/data
+
+   In ``$data_dir/SemanticScuttle/``, copy ``config.php.dist`` to
+   ``config.php`` and continue with  configuration_.