=====================
 Installing Ansel H5
=====================

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

This document contains instructions for installing the Ansel Photo Manager.

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


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

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

1. A working Horde installation.

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

   .. Important:: Ansel 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 Ansel. Many of Ansel's prerequisites are also
                  Horde prerequisites. Additionally, many of Ansel's optional
                  features are configured via the Horde install.

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

2. The following PHP capabilities:

   a. _`GD` support ``--with-gd``

      The GD extension provides functionality for image manipulation in
      PHP. You can alternatively use the imagick_ extension or the
      ImageMagick_ software, but one of these is **required**.

3. A database:

   Ansel needs a database to store information about images and galleries. Any
   database supported by Horde_Db will work; MySQL and PostgreSQL are the most
   tested. If you use MySQL, you need at least version 5.0.

4. The following PECL modules:
   (See `horde/docs/INSTALL`_ for instructions on installing PECL modules)

   a. _`imagick`

      The imagick module provides a quicker, more efficient interface to
      ImageMagick's capabilities. It provides better results when doing things
      like generating thumbnails with rounded corners and drop shadows. You can
      alternatively use the GD_ extension or the ImageMagick_ software, but one
      of these is **required**. The imagick extension **must** be compiled
      against ImageMagick version 6.2.9 or better, though version 6.5.7 or
      better is recommended.

   b. OpenCV

      The `php-facedetect module`_ provides the ability to detect human faces in
      images. If you would like to be able to have Ansel automatically detect
      faces in your images, you will need to install both the `OpenCV library`_
      as well as the phpfacedetect extension. You will still be able to manually
      select faces from your images if you do not have this extension installed.

      .. _`OpenCV library`: http://sourceforge.net/projects/opencvlibrary/
      .. _`php-facedetect module`: http://www.xarg.org/project/php-facedetect/

   c. libpuzzle

      The `libpuzzle library`_ provides the ability to determine similarities
      between images based on the image content. If you would like Ansel to be
      able to provide recognition of similar images and similar faces, you will
      need to install this module.

      .. _`libpuzzle library`: http://libpuzzle.pureftpd.org/project/libpuzzle

5. The _`ImageMagick` software.

   If using the `ImageMagick software`_ you need to set the path to the
   ``convert`` utility in Horde's configuration screen
   (``Administration/Configuration/Horde/Image Manipulation``). You can
   alternatively use the GD_ extension or the imagick_ extension, but one of
   these is **required**. If using ImageMagick software, version 6.5.7 or better
   is recommended. Earlier versions *may* work, but some effects may produce
   errors. The absolute minimum version that will work at all with Ansel is
   6.2.9.

   .. _`ImageMagick software`: http://www.imagemagick.org/

6. Agora, the Horde forums application.

   Agora_ provides the ability for comments to be added to photos via the
   forums API. If you want your users to be able to comment on photos, an
   application that provides the forums API is **required**.  Agora_ is
   currently the only such Horde application, but please be aware that
   currently Agora_ is not officially released in a stable version, so use at
   your own risk.

   .. _Agora: http://www.horde.org/apps/agora

Installing Ansel
================

The **RECOMMENDED** way to install Ansel is using the PEAR installer.
Alternatively, if you want to run the latest development code or get the
latest not yet released fixes, you can install Ansel 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 Ansel through PEAR now, the installer will automatically
install any dependencies of Ansel too. If you want to install Ansel 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/ansel-alpha

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

   pear install horde/ansel-alpha

If you want to install Ansel 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/ansel-alpha

Installing from Git
~~~~~~~~~~~~~~~~~~~

See http://www.horde.org/source/git.php


Configuring Ansel
=================

1. Configuring Ansel

   You must login to Horde as a Horde Administrator to finish the
   configuration of Ansel. 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 ``Photos`` from the selection list of
   applications. Fill in or change any configuration values as needed. When
   done click on ``Generate Photos Configuration`` to generate the
   ``conf.php`` file. If your web server doesn't have write permissions to the
   Ansel 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 ``ansel/config/conf.php``.

   Note for users of Lighttpd web server: The pretty url generation relies on
   rewrite rules being configured on your web server. Since lighttpd does not
   support .htaccess files like Apache, there is also a configuration file for
   lighttpd included that contains the necessary rewrite rules. This file is::

       docs/lighttpd-ansel.conf

   Instructions for using it are included in the file.

   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 Ansel's
   appearance and behavior. See the header of the configuration files for
   details and examples. The defaults will be correct for most sites.

2. Creating the database tables

   Once you finished the configuration in the previous step, you can create all
   database tables by clicking the ``DB schema is out of date.`` link in the
   Ansel row of the configuration screen.

   Alternatively you creating the Ansel database tables can be accomplished with
   horde's ``horde-db-migrate`` utility.  If your database is properly setup in
   the Horde configuration, just run the following::

      horde/bin/horde-db-migrate ansel

3. Testing Ansel

   Once you have configured Ansel, bring up the included test page in your Web
   browser to ensure that all necessary prerequisites have been met. See the
   `horde/docs/INSTALL`_ document for further details on the Horde test
   script.

   Next, use Ansel to create galleries and photos. Test at least the
   following:

   - Generate galleries
   - Upload photos
   - Edit photo properties
   - Edit photos
   - Delete photos
   - Delete galleries


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

If you encounter problems with Ansel, 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 Ansel is free software written by volunteers.
For information on reasonable support expectations, please read

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

Thanks for using Ansel!

The Ansel team


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