Changeset 27:b1d527287347 in mailjam for docs/src/install.rst

Timestamp:

May 23, 2012, 6:32:54 PM (12 years ago)

Author:

Borja Lopez <borja@…>

Branch:

default

Phase:

public

Message:

Added more information to the README file

Updated the architecture scheme so it fits the renaming of the project
to mailjam

Fixed the search path for configuration files. Now it searches on /etc
first, /usr/local/etc then.

Added more docs regarding the installation, configuration and running
of each component

File:

• docs/src/install.rst (modified) (12 diffs)

docs/src/install.rst

@@ -2 +2 @@
 =========================
 
+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::
 
@@ -14 +22 @@
 *2.6.x* too.
 
-Please, refer to your operating system package system documentation to learn
-more about how to install python.
+Please, refer to your operating system documentation to learn more about how 
+to install python.
 
 .. _install_mailjam:
@@ -22 +30 @@
 -----------------------
 
+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:
 
@@ -29 +41 @@
 You can install Mailjam using pip_::
 
-  pip install -e https://bitbucket.org/codigo23/mailjam#egg=mailjam
-
-.. note::
-
-   Mailjam has not been recorded/uploaded to pypi_ yet, so, in order to install 
-   it using pip you will have to provide the URL for the public Mailjam repo.
+  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:
@@ -41 +56 @@
 +++++++++++++++++++++++++++++
 
-You can not install Mailjam using easy_install_ yet (until we do record/upload 
-it to pypi)
+You can install Mailjam using easy_install_::
+
+  easy_install Mailjam
 
 .. _install_inside_virtualenv:
@@ -66 +82 @@
 And, once the environment has been activated, use pip to install Mailjam::
 
-  env$ pip install -e https://bitbucket.org/codigo23/mailjam#egg=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:
@@ -82 +105 @@
 ********
 
-**There are no releases yet**. You will have to install it from the repository.
-
-.. _install_from_repository:
-
-From repository
-***************
-
-The source code of Mailjam is hosted in bitbucket_ [1]_. 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::
+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
@@ -110 +128 @@
    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:
 
@@ -115 +159 @@
 ------------------
 
-TBW
+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:
@@ -122 +225 @@
 ---------------
 
-TBW
+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:
@@ -129 +244 @@
 -------------------------------
 
-TBW
+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
@@ -140 +266 @@
 .. _sudo: http://sudo.ws
 
-.. [1] https://bitbucket.org/codigo23/mailjam
+.. [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