=====================
 Installing Chora H5
=====================

:Contact: chora@lists.horde.org

.. contents:: Contents
.. section-numbering::


This document contains instructions for installing the Chora Repository Viewer
on your system.

For information on the capabilities and features of Chora, see the file
README_ in the top-level directory of the Chora distribution.


Prerequisites
=============

To function properly, Chora **requires** the following:

1. A working Horde installation.

   Chora runs within the `Horde Application Framework`_, a set of common tools
   for web applications written in PHP.  You must install Horde before
   installing Chora.

   .. Important:: Chora H5 requires version 5.0+ of the Horde Framework -
                  earlier versions of Horde will **not** work.

   .. Important:: Be sure to have completed all of the steps in the
                  `horde/docs/INSTALL`_ file for the Horde Framework before
                  installing Chora. Many of Chora's prerequisites are also
                  Horde prerequisites. Additionally, many of Chora's optional
                  features are configured via the Horde install.

   .. _`Horde Application Framework`: http://www.horde.org/apps/horde

2. A VCS repository to view.

   Chora can display any number of local and remote repositories. If accessing
   a local repository, the user under which the web server is running needs
   read access to the repositories.

   TODO: Documentation on the various drivers

3. VCS binaries.

   Depending on which kind of repositories you want to use, you need SVN
   (http://subversion.tigris.org/), RCS/CVS (http://www.cvshome.org/), or
   Git (http://git-scm.com/) binaries.


Installing Chora
================

There are several ways to install Chora. The recommended way to install Chora
is using the PEAR installer. Alternatively it can be installed from
tarballs. Finally, if you want to run the latest development code, or get the
latest, not yet released, fixes, you can install Chora from Git.


Installing with PEAR
~~~~~~~~~~~~~~~~~~~~

First follow the instructions in `horde/docs/INSTALL`_ to prepare a PEAR
environment for Horde and install the Horde Framework.

When installing Chora through PEAR now, the installer will automatically
install any dependencies of Chora too. If you want to install Chora with all
optional dependencies, but without the binary PECL packages that need to be
compiled, specify both the ``-a`` and the ``-B`` flag::

   pear install -a -B horde/chora

By default, only the required dependencies will be installed::

   pear install horde/chora

If you want to install Chora even with all binary dependencies, you need to
remove the ``-B`` flag. Please note that this might also try to install PHP
extensions through PECL that might need further configuration or activation in
your PHP configuration::

   pear install -a horde/chora


Installing from Release Tarballs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. Important:: As of today, there are no tarballs released for Chora 3
               yet. Please use the `Installing with PEAR`_ method to install
               Chora 3.

Chora can be obtained from the Horde website and FTP server, at

   http://www.horde.org/apps/chora

   ftp://ftp.horde.org/pub/chora/

Or use the mirror closest to you:

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

Chora 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, Chora is installed directly underneath Horde in the
webserver's document tree.

Since Chora 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/chora-x.y.z.tar.gz
   mv chora-x.y.z chora

and would then find Chora at the URL::

   http://your-server/horde/chora/


Configuring Chora
=================

1. Configuring Chora

   You must login to Horde as a Horde Administrator to finish the
   configuration of Chora.  Use the Horde ``Administration`` menu item to get
   to the administration page, and then click on the ``Configuration`` icon to
   get the configuration page.  Select ``Version Control`` from the selection
   list of applications.  Fill in or change any configuration values as
   needed.  When done click on ``Generate Version Control Configuration`` to
   generate the ``conf.php`` file.  If your web server doesn't have write
   permissions to the Chora configuration directory or file, it will not be
   able to write the file.  In this case, go back to ``Configuration`` and
   choose one of the other methods to create the configuration file
   ``chora/config/conf.php``.

   To configure Chora, change to the ``config/`` directory of the installed
   distribution, and copy the ``backends.php.dist`` configuration file to
   ``backends.php`` and edit it to your needs. You must be sure to list your
   repository names and configuration information in ``backends.php``.

   Documentation on the format and purpose of the other configuration files in
   the ``config/`` directory can be found in each file. You may create
   ``*.local.php`` versions of these files if you wish to customize Chora's
   appearance and behavior. See the header of the configuration files for
   details and examples. The defaults will be correct for most sites.

2. Testing Chora

   Go to the Chora URL, and test out all the functionality to ensure it is
   working.

   If you run into a problem with annotationsin CVS repositories, it is
   because some versions of CVS insist on having the ``CVSROOT/history`` file
   as world-writable.  Either make this file world-writable, or simply delete
   it (you don't need to have it for CVS to work).


Obtaining Support
=================

If you encounter problems with Chora, help is available!

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

  http://wiki.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/community/mail

Lastly, Horde developers, contributors and users may also be found on IRC,
on the channel #horde on the Freenode Network (irc.freenode.net).

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

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

Thanks for using Chora!

The Horde team


.. _README: README
.. _INSTALL:
.. _`horde/docs/INSTALL`: ../../horde/docs/INSTALL
.. _`horde/docs/TRANSLATIONS`: ../../horde/docs/TRANSLATIONS
