SemanticScuttle/doc/INSTALL.txt

============================
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 database
2. Import ``data/tables.sql`` into that database, i.e.
   run ::

   $ mysql -umyusername semanticscuttle < data/tables.sql

   on the shell ("semanticscuttle" being the database name)

   If you run PostgreSQL, use ``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_.