========================
|| INSTALLING Giapeto ||
========================

Copyright 2002-2005 <marko@oblo.com>

Installation instructions for Giapeto!

PREREQUISITES
-------------

The following are ESSENTIAL for a Giapeto to function:

  1. The latest CVS install of Horde

     Giapeto relies on many Horde functions which have also been fine
     tuned only in the later versions of Horde.

  2. A functioning Virtual File System (VFS) in Horde.

     An example of such a configuration for the SQL backend is show in
     the following section on configuring Giapeto.


INSTALLING GIAPETO
------------------

Giapeto is written in PHP, and must be installed in a web-accessible
directory. The precise location of this directory will differ from
system to system. Conventionally, Giapeto is installed directly
underneath Horde in the webserver's document tree.

Since Giapeto is written in PHP, there is no compilation necessary;
simply expand the distribution where you want it to reside and rename
the root directory of the distribution to whatever you wish to appear
in the URL. For example, with the Apache webserver's default document
root of '/usr/local/apache/htdocs', you would type:

   cd /usr/local/apache/htdocs/horde
   tar zxvf /path/to/giapeto-0.8.tar.gz
   mv giapeto-0.8 giapeto

and would then find Giapeto at the URL

   http://your-server/horde/giapeto/


CONFIGURING GIAPETO
---------------

1. Configuring Horde for Giapeto

   a. Register the application

      If the horde/config/registry.php does not already contain the
      section for Giapeto you need to add something like this:

          $this->applications['giapeto'] = array(
              'fileroot' => dirname(__FILE__) . '/../giapeto',
              'webroot' => $this->applications['horde']['webroot'] . '/giapeto',
              'name' => _("CMS"),
              'status' => 'active',
              'menu_parent' => 'webserver'
          );

   b. Configure VFS

      Giapeto requires that the pages be stored in the VFS of Horde.
      You can choose whatever backend is avaible for your VFS, and
      here is a sample configuration for the SQL backend:

          $conf['vfs']['type'] = 'sql';
          $conf['vfs']['params'] = array();
          $conf['vfs']['params']['phptype'] = 'mysql';
          $conf['vfs']['params']['hostspec'] = 'localhost';
          $conf['vfs']['params']['username'] = 'yourusername';
          $conf['vfs']['params']['password'] = 'yourpassword';
          $conf['vfs']['params']['database'] = 'yourdatabase';
          $conf['vfs']['params']['table'] = 'yourtable';

2. Configuring Giapeto

   a. conf.xml

   Giapeto uses the xml format for generating its configuration files.
   As admin go into the administration panel of horde. Select the
   option "configuration" and generate the configuration for the
   CMS (giapeto) module.

   The most important setting here is this one:
     "Should URL's be completely rewritten or use GET?"
   If choosing "rewrite" you can use Apache to hide the program
   codes from the url, thus making your site's pages friendlier to
   search engines. (See section below on Apache configuration.)
   However, note that it is by far easier to start off with the "get"
   method initially, as at least any installation/configuration error
   messages will always be displayed properly. Once you have Giapeto
   up and running properly, you can then switch to "rewrite" just
   by re-running the configuration tool.

   b. Configuration files

   To configure Giapeto, change to the config/ directory of the
   installed distribution, and make copies of all of the configuration
   "dist" files without the "dist" suffix:

      cd config/
      for foo in *.dist; do cp $foo `basename $foo .dist`; done

   Or if you are installing Giapeto an a Windows system:

      cd config
      copy *.dist *.

   Documentation on the format of those files can be found in each
   file. You must at least complete the "Preferences System Settings"
   section of horde.php and provide paths to helper applications in
   mime_drivers.php. Configuration of applications in registry.php is
   documented in the INSTALL file of each application.

   The other files in that directory need only be modified if you wish
   to customize Giapeto's appearance or behaviour -- the defaults will
   work at most sites.

   Note for international users:  Giapeto uses GNU gettext to provide local
   translations of text displayed by applications; the translations are
   found in the po/ directory.  If a translation is not yet available
   for your locale (and you wish to create one), or if you're having
   trouble using a provided translation, please see the
   horde/DOCS/translations file for instructions.


3. Install and customise Giapeto templates

   Giapeto uses templates that can be customised at will and are
   located in the config/templates directory. There are two sets of
   templates. The ones found in manage/ are support-type templates
   used by Giapeto for showing the compose page for example. The
   onese found in pages/ are used to display the actual pages that
   are created once Giapeto is installed.

   To install, its enough that you go into each directory and
   make copies of all the "dist" template files without the "dist"
   suffix:

      cd templates/
      for foo in *.dist; do cp $foo `basename $foo .dist`; done

   Or if you are installing Giapeto an a Windows system:

      cd templates
      copy *.dist *.

4. Optional: apache configuration

      If you want to take advantage of the Apache mod_rewrite
      function to hide all the argument passing and hence
      optimise your website for spiders and search engines, you
      need to either make sure that the provided .htaccess file is
      read by your server, or if you have .htaccess files turned off
      or do not allow them to set mod_rewrite settings, copy the rules
      into the appropriate place.

OBTAINING SUPPORT
-----------------

If you encounter problems with Giapeto, help is available!

The Horde Frequently Asked Questions List (FAQ), available on the Web
at

  http://www.horde.org/faq/

The Horde Project runs a number of mailing lists, for individual
applications and for issues relating to the project as a whole.
Information, archives, and subscription information can be found at

  http://www.horde.org/mail/

Lastly, Horde developers, contributors and users also make occasional
appearances on IRC, on the channel #horde on the Freenode Network
(irc.freenode.net).

Please keep in mind that Giapeto is free software written by volunteers.
For information on reasonable support expectations, please read

  http://www.horde.org/support.php

Thanks for using Giapeto!

The Horde team
giapeto@lists.horde.org

$Horde: giapeto/docs/INSTALL,v 1.20 2006/03/04 23:40:39 chuck Exp $
