Installation instructions
=========================

Installing Mailjam is quite easy. If you have some experience installing 
Python_ packages [1]_, you already know how to do it. Mailjam is a standard
Python_ package available on pypi_ [3]_ so just use your favourite tool
(pip_, easy_install_, etc) to intall it.

Keep reading if you want to learn more about the different options/choices
you have when installing Mailjam.

.. contents::

.. _install_dependencies:

First, install dependencies
---------------------------

So far, the only dependency you will need in order to run mailjam is Python_

Mailjam has been tested with python *2.7.x*, but it should work with versions
*2.6.x* too.

Please, refer to your operating system documentation to learn more about how 
to install python.

.. _install_mailjam:

Second, install Mailjam
-----------------------

You can install Mailjam using one of the available tools for installing Python_
packages, or you can install it from sources. Keep reading to learn more about
it.

.. _install_with_pip:

Installing using pip
++++++++++++++++++++

You can install Mailjam using pip_::

  pip install Mailjam

.. note::

   The previous command will install the latest release from pypi_. If you
   would like to install the latest *bleeding edge* sources (unstable code),
   you can do it using pip_ too::

     pip install -e https://bitbucket.org/codigo23/mailjam#egg=mailjam

.. _install_with_easy_install:

Installing using easy_install
+++++++++++++++++++++++++++++

You can install Mailjam using easy_install_::

  easy_install Mailjam

.. _install_inside_virtualenv:

Installing inside a virtualenv
++++++++++++++++++++++++++++++

You can install Mailjam inside a virtualenv_. Just create a virtualenv::

  virtualenv /path/to/your/env

Then activate it::

  source /path/to/your/env/bin/activate

.. note::

   If your shell is **csh**/**tcsh** remember you have to activate the 
   environment this way::

     source /path/to/your/env/bin/activate.csh

And, once the environment has been activated, use pip to install Mailjam::

  env$ pip install Mailjam

.. note::

   Remember that you can install the latest *bleeding edge* version using 
   pip_ too::
   
     env$ pip install -e https://bitbucket.org/codigo23/mailjam#egg=mailjam

.. _install_from_sources:

Installing from sources
+++++++++++++++++++++++

When installing from sources, you can download one of the official releases
or you can go with the *bleeding edge* and get a copy of the official source
code repository.

.. _install_from_release:

Releases
********

You can grab a copy of the latest release from pypi_:

http://pypi.python.org/packages/source/m/mailjam/

After downloaded, you have to unpack the sources::

  tar -zxvvf mailjam-0.1.0.tar.gz

This will create a directory called *mailjam-0.1.0*, go inside that directory
and run::

  python setup.py install

.. warning::

   If you want to install it *system-wide*, probably you will need *root*
   privileges (check your OS documentation to learn more about how to get
   *root* privileges - for example using sudo_)

.. note::

   This process will work inside a virtualenv_ too.

.. _install_from_repository:

From repository
***************

The source code of Mailjam is hosted in bitbucket_ [2]_. In order to grab
the latest sources you need Mercurial_.

To get a copy of the sources, just *clone* the repository::

  hg clone https://bitbucket.org/codigo23/mailjam mailjam-repo

Then, go inside the *mailjam-repo* directory and run::

  python setup.py install

.. warning::

   If you want to install it *system-wide*, probably you will need *root*
   privileges (check your OS documentation to learn more about how to get
   *root* privileges - for example using sudo_)

.. note::

   This process will work inside a virtualenv_ too.

.. _install_setting_up_mailjam:

Setting up Mailjam
------------------

In order to setup Mailjam, you will have to create the needed 
:doc:`configuration files <configuration>`. Each component has its own
configuration file:

- The :ref:`Mailjam daemon <overview_mailjam_daemon>` configuration file is 
  :ref:`mailjam.conf <configuration_daemon>`

- The :ref:`Mailjam MTA client <overview_mailjam_mta_client>` configuration 
  file is :ref:`mailjam-mta.conf <configuration_mta_client>`

- The :ref:`Mailjam CLI client <overview_mailjam_cli_client>` configuration 
  file is :ref:`mailjam-cli.conf <configuration_cli_client>`

Refer to each configuration file documentation to learn more about the different
settings you can customize.

Each component will search for its configuration file in a list of predefined
locations, but you can override that behaviour using the *-c* parameter when
starting the component. 

.. note::

   Mailjam will search for the config files, in order, through the following 
   paths:

   1. /etc/mailjam

   2. /etc

   3. /usr/local/etc/mailjam

   4. /usr/local/etc

   5. the *conf* directory within the sources (or the installed *egg* [4]_)

For example, you can start the :ref:`overview_mailjam_daemon` passing 
*/var/db/mailjam/mailjam.conf* as its configuration file::

  mailjam-server -c /var/db/mailjam/mailjam.conf

.. seealso::

   :doc:`running` contains more information about how to run the different 
   components.

If you have installed Mailjam using pip_, easy_install_ or even from sources,
the setup process should have taken care of the configuration files, adding
a copy of the default files included in the sources to the default 
destination.

.. warning::

   The default destination will be different based on your operating system.
   For example, in most linux servers it will copy the files to */etc/mailjam*,
   while in BSD servers it will copy the files to */usr/local/etc/mailjam*.

.. seealso::

   :doc:`Configuration files, settings and formats documentation <configuration>`


.. _install_running_mailjam:

Running Mailjam
---------------

In order to run a full Mailjam environment, you will have to start the different
components separately:

1. :ref:`Start the daemon <running_daemon>`

2. :ref:`Run the cli client and manage your mailing lists <running_cli_client>`

3. :ref:`Add as much MTA clients as you need to your mail server<running_mta_client>`

The daemon will have to be running all the time (it is the component responsible
for providing information to the clients). You will need the CLI client to add, 
edit or delete mailing lists and each MTA client will be responsible to handle 
incoming emails for each mailing list.

.. _install_running_tests:

Running tests (developers only)
-------------------------------

Just in case you were wondering, **yes**, Mailjam code has some tests you can 
run to check everything is ok and that the software should run smoothly on your
server(s).

To run the tests, simply get a copy of the sources from our public repository::

  hg clone https://bitbucket.org/codigo23/mailjam mailjam-repo

then run the tests::

  cd mailjam-repo && ./bin/run_tests


.. _Python: http://python.org
.. _pip: http://www.pip-installer.org/en/latest/index.html
.. _pypi: http://pypi.python.org/pypi
.. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
.. _virtualenv: http://www.virtualenv.org/en/latest/index.html
.. _bitbucket: https://bitbucket.org
.. _Mercurial: http://mercurial.selenic.com
.. _sudo: http://sudo.ws

.. [1] http://docs.python.org/tutorial/modules.html#packages
.. [2] https://bitbucket.org/codigo23/mailjam
.. [3] http://pypi.python.org/pypi/mailjam
.. [4] http://svn.python.org/projects/sandbox/trunk/setuptools/doc/formats.txt