source: mailjam/docs/src/_build/html/_sources/install.txt

Last change on this file was 27:b1d527287347, checked in by Borja Lopez <borja@…>, 12 years ago

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 size: 7.4 KB
Line 
1Installation instructions
2=========================
3
4Installing Mailjam is quite easy. If you have some experience installing
5Python_ packages [1]_, you already know how to do it. Mailjam is a standard
6Python_ package available on pypi_ [3]_ so just use your favourite tool
7(pip_, easy_install_, etc) to intall it.
8
9Keep reading if you want to learn more about the different options/choices
10you have when installing Mailjam.
11
12.. contents::
13
14.. _install_dependencies:
15
16First, install dependencies
17---------------------------
18
19So far, the only dependency you will need in order to run mailjam is Python_
20
21Mailjam has been tested with python *2.7.x*, but it should work with versions
22*2.6.x* too.
23
24Please, refer to your operating system documentation to learn more about how
25to install python.
26
27.. _install_mailjam:
28
29Second, install Mailjam
30-----------------------
31
32You can install Mailjam using one of the available tools for installing Python_
33packages, or you can install it from sources. Keep reading to learn more about
34it.
35
36.. _install_with_pip:
37
38Installing using pip
39++++++++++++++++++++
40
41You can install Mailjam using pip_::
42
43 pip install Mailjam
44
45.. note::
46
47 The previous command will install the latest release from pypi_. If you
48 would like to install the latest *bleeding edge* sources (unstable code),
49 you can do it using pip_ too::
50
51 pip install -e https://bitbucket.org/codigo23/mailjam#egg=mailjam
52
53.. _install_with_easy_install:
54
55Installing using easy_install
56+++++++++++++++++++++++++++++
57
58You can install Mailjam using easy_install_::
59
60 easy_install Mailjam
61
62.. _install_inside_virtualenv:
63
64Installing inside a virtualenv
65++++++++++++++++++++++++++++++
66
67You can install Mailjam inside a virtualenv_. Just create a virtualenv::
68
69 virtualenv /path/to/your/env
70
71Then activate it::
72
73 source /path/to/your/env/bin/activate
74
75.. note::
76
77 If your shell is **csh**/**tcsh** remember you have to activate the
78 environment this way::
79
80 source /path/to/your/env/bin/activate.csh
81
82And, once the environment has been activated, use pip to install Mailjam::
83
84 env$ pip install Mailjam
85
86.. note::
87
88 Remember that you can install the latest *bleeding edge* version using
89 pip_ too::
90
91 env$ pip install -e https://bitbucket.org/codigo23/mailjam#egg=mailjam
92
93.. _install_from_sources:
94
95Installing from sources
96+++++++++++++++++++++++
97
98When installing from sources, you can download one of the official releases
99or you can go with the *bleeding edge* and get a copy of the official source
100code repository.
101
102.. _install_from_release:
103
104Releases
105********
106
107You can grab a copy of the latest release from pypi_:
108
109http://pypi.python.org/packages/source/m/mailjam/
110
111After downloaded, you have to unpack the sources::
112
113 tar -zxvvf mailjam-0.1.0.tar.gz
114
115This will create a directory called *mailjam-0.1.0*, go inside that directory
116and run::
117
118 python setup.py install
119
120.. warning::
121
122 If you want to install it *system-wide*, probably you will need *root*
123 privileges (check your OS documentation to learn more about how to get
124 *root* privileges - for example using sudo_)
125
126.. note::
127
128 This process will work inside a virtualenv_ too.
129
130.. _install_from_repository:
131
132From repository
133***************
134
135The source code of Mailjam is hosted in bitbucket_ [2]_. In order to grab
136the latest sources you need Mercurial_.
137
138To get a copy of the sources, just *clone* the repository::
139
140 hg clone https://bitbucket.org/codigo23/mailjam mailjam-repo
141
142Then, go inside the *mailjam-repo* directory and run::
143
144 python setup.py install
145
146.. warning::
147
148 If you want to install it *system-wide*, probably you will need *root*
149 privileges (check your OS documentation to learn more about how to get
150 *root* privileges - for example using sudo_)
151
152.. note::
153
154 This process will work inside a virtualenv_ too.
155
156.. _install_setting_up_mailjam:
157
158Setting up Mailjam
159------------------
160
161In order to setup Mailjam, you will have to create the needed
162:doc:`configuration files <configuration>`. Each component has its own
163configuration file:
164
165- The :ref:`Mailjam daemon <overview_mailjam_daemon>` configuration file is
166 :ref:`mailjam.conf <configuration_daemon>`
167
168- The :ref:`Mailjam MTA client <overview_mailjam_mta_client>` configuration
169 file is :ref:`mailjam-mta.conf <configuration_mta_client>`
170
171- The :ref:`Mailjam CLI client <overview_mailjam_cli_client>` configuration
172 file is :ref:`mailjam-cli.conf <configuration_cli_client>`
173
174Refer to each configuration file documentation to learn more about the different
175settings you can customize.
176
177Each component will search for its configuration file in a list of predefined
178locations, but you can override that behaviour using the *-c* parameter when
179starting the component.
180
181.. note::
182
183 Mailjam will search for the config files, in order, through the following
184 paths:
185
186 1. /etc/mailjam
187
188 2. /etc
189
190 3. /usr/local/etc/mailjam
191
192 4. /usr/local/etc
193
194 5. the *conf* directory within the sources (or the installed *egg* [4]_)
195
196For example, you can start the :ref:`overview_mailjam_daemon` passing
197*/var/db/mailjam/mailjam.conf* as its configuration file::
198
199 mailjam-server -c /var/db/mailjam/mailjam.conf
200
201.. seealso::
202
203 :doc:`running` contains more information about how to run the different
204 components.
205
206If you have installed Mailjam using pip_, easy_install_ or even from sources,
207the setup process should have taken care of the configuration files, adding
208a copy of the default files included in the sources to the default
209destination.
210
211.. warning::
212
213 The default destination will be different based on your operating system.
214 For example, in most linux servers it will copy the files to */etc/mailjam*,
215 while in BSD servers it will copy the files to */usr/local/etc/mailjam*.
216
217.. seealso::
218
219 :doc:`Configuration files, settings and formats documentation <configuration>`
220
221
222.. _install_running_mailjam:
223
224Running Mailjam
225---------------
226
227In order to run a full Mailjam environment, you will have to start the different
228components separately:
229
2301. :ref:`Start the daemon <running_daemon>`
231
2322. :ref:`Run the cli client and manage your mailing lists <running_cli_client>`
233
2343. :ref:`Add as much MTA clients as you need to your mail server<running_mta_client>`
235
236The daemon will have to be running all the time (it is the component responsible
237for providing information to the clients). You will need the CLI client to add,
238edit or delete mailing lists and each MTA client will be responsible to handle
239incoming emails for each mailing list.
240
241.. _install_running_tests:
242
243Running tests (developers only)
244-------------------------------
245
246Just in case you were wondering, **yes**, Mailjam code has some tests you can
247run to check everything is ok and that the software should run smoothly on your
248server(s).
249
250To run the tests, simply get a copy of the sources from our public repository::
251
252 hg clone https://bitbucket.org/codigo23/mailjam mailjam-repo
253
254then run the tests::
255
256 cd mailjam-repo && ./bin/run_tests
257
258
259.. _Python: http://python.org
260.. _pip: http://www.pip-installer.org/en/latest/index.html
261.. _pypi: http://pypi.python.org/pypi
262.. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
263.. _virtualenv: http://www.virtualenv.org/en/latest/index.html
264.. _bitbucket: https://bitbucket.org
265.. _Mercurial: http://mercurial.selenic.com
266.. _sudo: http://sudo.ws
267
268.. [1] http://docs.python.org/tutorial/modules.html#packages
269.. [2] https://bitbucket.org/codigo23/mailjam
270.. [3] http://pypi.python.org/pypi/mailjam
271.. [4] http://svn.python.org/projects/sandbox/trunk/setuptools/doc/formats.txt
Note: See TracBrowser for help on using the repository browser.