==============
 Installation
==============

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

You only need Python 2.5. (Other python versions are currently not
supported.)

First installation
==================

CAUTION: icemac.addressbook can't be installed using ``easy_install``,
you have to follow these simple steps.

Neither you need any root privileges nor it installs anything outside
its directory.

1. Download the source distribution (see Download_).

2. Extract the downloaded file.

3. Run ``install.py`` using your desired python, e. g.::

   $ python2.5 install.py

4. Answer the questions about admin user name, password and so on.

5. Run the tests. See `Run the tests`_

6. Start the application. See `Run the application`_

Update
======

- When you are updating from version 0.3.x or earlier follow the steps
  described in `First installation`_ followed by the steps described
  in `Second part of steps for older versions`_.

- When you are updating from version 0.4 or newer follow these steps:

   1. Download and extract the source distribution (see Download_) to a
   new a directory.

   2. Run ``install.py`` using your desired python added by the path
   to the previous installation. This way values you entered
   previously are used as defaults instead of the application
   defaults.  Example::

     $ python2.5 install.py ../icemac.addressbook-0.4

   3. Answer the questions about admin user name, password and so on.

   4. Start the new instance of the application.

- If you get an error when running the application after updating
  which looks like::

    zope.app.generations.interfaces.UnableToEvolve: (..., u'icemac.addressbook', ...)

  Then you have to upgrade to version 0.5.x first and start the
  application, so that legacy data can be converted. Version 1.x is no
  longer compatible with these older versions.


Second part of steps for older versions
---------------------------------------

1. Stop the old instance of the application.

2. Create a backup of the ZODB og the old instance using::

   $ bin/backup

3. Copy the backup directory (``var/backups``) to the new instance.

4. Restore the backup into the new instance using::

   $ bin/restore

5. Start the new instance of the application.

Run the tests
=============

Run the unit tests and functional tests using::

  $ bin/test

Run the application
===================

To run the application instance in foreground start using::

  $ bin/addressbook fg

To run it as a demon process start using::

  $ bin/addressbook start

To stop the demon process call::

  $ bin/addressbook stop

The default URL is to access the application is::

  http://127.0.0.1:8080

To log-in at this URL you need the username and password you chose
when running ``install.py``. The are stored in ``admin.zcml``.

Create a new address book using the `add address book` link on the
right. How to create new users inside this address book is described
in `Create new users`_.


Change configuration of the installation
========================================

The values you entered during installation resp. update are stored in
a file named `install.user.ini` in the address book directory.

To change the configuration values call `install.py` using python and
enter a `.` as parameter like this::

  $ python2.5 install.py .

The configuration questions get presented to you with your previously
entered values as default.

To remove additional packages you have to edit the ``[package]``
section of `install.user.ini`. There is currently no other way for
removal.

=================
 User management
=================

Roles
=====

Access to the address book is only granted after authentication. There
are three roles to authorize a user:

- visitor: visit all person's data, search and export, change own
  password

- editor: permissions of visitor + edit all person's data, change own
  log-in name

- administrator: permissions of editor + create and change address
  book and users

Create new users
================

Users are persons from the address book augmented by log-in
information.

To create the first new user inside an address book the adminstrator
(who was created in `First installation`_) has to log-in and then do
the following:

  1. create a new person with an e-mail address using `Add person`.

  2. create a new user using `Master data --> Users --> Add user`.

The newly created user has now a log-in (e-mail address) for the
address book the person belonges to.