==============
 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
======

- If 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`_.

- If 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.

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.