source: mailjam/docs/src/_build/html/install.html@ 33:8efa7a7802d4

Last change on this file since 33:8efa7a7802d4 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: 22.8 KB
RevLine 
[13]1
2
3<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
6
7<html xmlns="http://www.w3.org/1999/xhtml">
8 <head>
9 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
10
[16]11 <title>Installation instructions &mdash; Mailjam 0.1.0 documentation</title>
[13]12
13 <link rel="stylesheet" href="_static/default.css" type="text/css" />
14 <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
15
16 <script type="text/javascript">
17 var DOCUMENTATION_OPTIONS = {
18 URL_ROOT: '',
19 VERSION: '0.1.0',
20 COLLAPSE_INDEX: false,
21 FILE_SUFFIX: '.html',
22 HAS_SOURCE: true
23 };
24 </script>
25 <script type="text/javascript" src="_static/jquery.js"></script>
26 <script type="text/javascript" src="_static/underscore.js"></script>
27 <script type="text/javascript" src="_static/doctools.js"></script>
[16]28 <link rel="top" title="Mailjam 0.1.0 documentation" href="index.html" />
[13]29 <link rel="next" title="Configuration" href="configuration.html" />
[16]30 <link rel="prev" title="Overview of mailjam’s architecture" href="overview.html" />
[13]31 </head>
32 <body>
33 <div class="related">
34 <h3>Navigation</h3>
35 <ul>
36 <li class="right" style="margin-right: 10px">
37 <a href="genindex.html" title="General Index"
38 accesskey="I">index</a></li>
39 <li class="right" >
40 <a href="configuration.html" title="Configuration"
41 accesskey="N">next</a> |</li>
42 <li class="right" >
[16]43 <a href="overview.html" title="Overview of mailjam’s architecture"
[13]44 accesskey="P">previous</a> |</li>
[16]45 <li><a href="index.html">Mailjam 0.1.0 documentation</a> &raquo;</li>
[13]46 </ul>
47 </div>
48
49 <div class="document">
50 <div class="documentwrapper">
51 <div class="bodywrapper">
52 <div class="body">
53
54 <div class="section" id="installation-instructions">
[27]55<h1><a class="toc-backref" href="#id9">Installation instructions</a><a class="headerlink" href="#installation-instructions" title="Permalink to this headline"></a></h1>
56<p>Installing Mailjam is quite easy. If you have some experience installing
57<a class="reference external" href="http://python.org">Python</a> packages <a class="footnote-reference" href="#id5" id="id1">[1]</a>, you already know how to do it. Mailjam is a standard
58<a class="reference external" href="http://python.org">Python</a> package available on <a class="reference external" href="http://pypi.python.org/pypi">pypi</a> <a class="footnote-reference" href="#id7" id="id2">[3]</a> so just use your favourite tool
59(<a class="reference external" href="http://www.pip-installer.org/en/latest/index.html">pip</a>, <a class="reference external" href="http://peak.telecommunity.com/DevCenter/EasyInstall">easy_install</a>, etc) to intall it.</p>
60<p>Keep reading if you want to learn more about the different options/choices
61you have when installing Mailjam.</p>
[13]62<div class="contents topic" id="contents">
63<p class="topic-title first">Contents</p>
64<ul class="simple">
[27]65<li><a class="reference internal" href="#installation-instructions" id="id9">Installation instructions</a><ul>
66<li><a class="reference internal" href="#first-install-dependencies" id="id10">First, install dependencies</a></li>
67<li><a class="reference internal" href="#second-install-mailjam" id="id11">Second, install Mailjam</a><ul>
68<li><a class="reference internal" href="#installing-using-pip" id="id12">Installing using pip</a></li>
69<li><a class="reference internal" href="#installing-using-easy-install" id="id13">Installing using easy_install</a></li>
70<li><a class="reference internal" href="#installing-inside-a-virtualenv" id="id14">Installing inside a virtualenv</a></li>
71<li><a class="reference internal" href="#installing-from-sources" id="id15">Installing from sources</a><ul>
72<li><a class="reference internal" href="#releases" id="id16">Releases</a></li>
73<li><a class="reference internal" href="#from-repository" id="id17">From repository</a></li>
[13]74</ul>
75</li>
76</ul>
77</li>
[27]78<li><a class="reference internal" href="#setting-up-mailjam" id="id18">Setting up Mailjam</a></li>
79<li><a class="reference internal" href="#running-mailjam" id="id19">Running Mailjam</a></li>
80<li><a class="reference internal" href="#running-tests-developers-only" id="id20">Running tests (developers only)</a></li>
[13]81</ul>
82</li>
83</ul>
84</div>
85<div class="section" id="first-install-dependencies">
[27]86<span id="install-dependencies"></span><h2><a class="toc-backref" href="#id10">First, install dependencies</a><a class="headerlink" href="#first-install-dependencies" title="Permalink to this headline"></a></h2>
[16]87<p>So far, the only dependency you will need in order to run mailjam is <a class="reference external" href="http://python.org">Python</a></p>
88<p>Mailjam has been tested with python <em>2.7.x</em>, but it should work with versions
[13]89<em>2.6.x</em> too.</p>
[27]90<p>Please, refer to your operating system documentation to learn more about how
91to install python.</p>
[13]92</div>
[16]93<div class="section" id="second-install-mailjam">
[27]94<span id="install-mailjam"></span><h2><a class="toc-backref" href="#id11">Second, install Mailjam</a><a class="headerlink" href="#second-install-mailjam" title="Permalink to this headline"></a></h2>
95<p>You can install Mailjam using one of the available tools for installing <a class="reference external" href="http://python.org">Python</a>
96packages, or you can install it from sources. Keep reading to learn more about
97it.</p>
[13]98<div class="section" id="installing-using-pip">
[27]99<span id="install-with-pip"></span><h3><a class="toc-backref" href="#id12">Installing using pip</a><a class="headerlink" href="#installing-using-pip" title="Permalink to this headline"></a></h3>
[16]100<p>You can install Mailjam using <a class="reference external" href="http://www.pip-installer.org/en/latest/index.html">pip</a>:</p>
[27]101<div class="highlight-python"><pre>pip install Mailjam</pre>
[13]102</div>
103<div class="admonition note">
104<p class="first admonition-title">Note</p>
[27]105<p>The previous command will install the latest release from <a class="reference external" href="http://pypi.python.org/pypi">pypi</a>. If you
106would like to install the latest <em>bleeding edge</em> sources (unstable code),
107you can do it using <a class="reference external" href="http://www.pip-installer.org/en/latest/index.html">pip</a> too:</p>
108<div class="last highlight-python"><pre>pip install -e https://bitbucket.org/codigo23/mailjam#egg=mailjam</pre>
109</div>
[13]110</div>
111</div>
112<div class="section" id="installing-using-easy-install">
[27]113<span id="install-with-easy-install"></span><h3><a class="toc-backref" href="#id13">Installing using easy_install</a><a class="headerlink" href="#installing-using-easy-install" title="Permalink to this headline"></a></h3>
114<p>You can install Mailjam using <a class="reference external" href="http://peak.telecommunity.com/DevCenter/EasyInstall">easy_install</a>:</p>
115<div class="highlight-python"><pre>easy_install Mailjam</pre>
116</div>
[13]117</div>
118<div class="section" id="installing-inside-a-virtualenv">
[27]119<span id="install-inside-virtualenv"></span><h3><a class="toc-backref" href="#id14">Installing inside a virtualenv</a><a class="headerlink" href="#installing-inside-a-virtualenv" title="Permalink to this headline"></a></h3>
[16]120<p>You can install Mailjam inside a <a class="reference external" href="http://www.virtualenv.org/en/latest/index.html">virtualenv</a>. Just create a virtualenv:</p>
[13]121<div class="highlight-python"><div class="highlight"><pre><span class="n">virtualenv</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">your</span><span class="o">/</span><span class="n">env</span>
122</pre></div>
123</div>
124<p>Then activate it:</p>
125<div class="highlight-python"><div class="highlight"><pre><span class="n">source</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">your</span><span class="o">/</span><span class="n">env</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">activate</span>
126</pre></div>
127</div>
128<div class="admonition note">
129<p class="first admonition-title">Note</p>
130<p>If your shell is <strong>csh</strong>/<strong>tcsh</strong> remember you have to activate the
131environment this way:</p>
132<div class="last highlight-python"><div class="highlight"><pre><span class="n">source</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">your</span><span class="o">/</span><span class="n">env</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">activate</span><span class="o">.</span><span class="n">csh</span>
133</pre></div>
134</div>
135</div>
[16]136<p>And, once the environment has been activated, use pip to install Mailjam:</p>
[27]137<div class="highlight-python"><pre>env$ pip install Mailjam</pre>
138</div>
139<div class="admonition note">
140<p class="first admonition-title">Note</p>
141<p>Remember that you can install the latest <em>bleeding edge</em> version using
142<a class="reference external" href="http://www.pip-installer.org/en/latest/index.html">pip</a> too:</p>
143<div class="last highlight-python"><pre>env$ pip install -e https://bitbucket.org/codigo23/mailjam#egg=mailjam</pre>
144</div>
[13]145</div>
146</div>
147<div class="section" id="installing-from-sources">
[27]148<span id="install-from-sources"></span><h3><a class="toc-backref" href="#id15">Installing from sources</a><a class="headerlink" href="#installing-from-sources" title="Permalink to this headline"></a></h3>
[13]149<p>When installing from sources, you can download one of the official releases
150or you can go with the <em>bleeding edge</em> and get a copy of the official source
151code repository.</p>
152<div class="section" id="releases">
[27]153<span id="install-from-release"></span><h4><a class="toc-backref" href="#id16">Releases</a><a class="headerlink" href="#releases" title="Permalink to this headline"></a></h4>
154<p>You can grab a copy of the latest release from <a class="reference external" href="http://pypi.python.org/pypi">pypi</a>:</p>
155<p><a class="reference external" href="http://pypi.python.org/packages/source/m/mailjam/">http://pypi.python.org/packages/source/m/mailjam/</a></p>
156<p>After downloaded, you have to unpack the sources:</p>
157<div class="highlight-python"><pre>tar -zxvvf mailjam-0.1.0.tar.gz</pre>
158</div>
159<p>This will create a directory called <em>mailjam-0.1.0</em>, go inside that directory
160and run:</p>
161<div class="highlight-python"><pre>python setup.py install</pre>
162</div>
163<div class="admonition warning">
164<p class="first admonition-title">Warning</p>
165<p class="last">If you want to install it <em>system-wide</em>, probably you will need <em>root</em>
166privileges (check your OS documentation to learn more about how to get
167<em>root</em> privileges - for example using <a class="reference external" href="http://sudo.ws">sudo</a>)</p>
168</div>
169<div class="admonition note">
170<p class="first admonition-title">Note</p>
171<p class="last">This process will work inside a <a class="reference external" href="http://www.virtualenv.org/en/latest/index.html">virtualenv</a> too.</p>
172</div>
[13]173</div>
174<div class="section" id="from-repository">
[27]175<span id="install-from-repository"></span><h4><a class="toc-backref" href="#id17">From repository</a><a class="headerlink" href="#from-repository" title="Permalink to this headline"></a></h4>
176<p>The source code of Mailjam is hosted in <a class="reference external" href="https://bitbucket.org">bitbucket</a> <a class="footnote-reference" href="#id6" id="id3">[2]</a>. In order to grab
[13]177the latest sources you need <a class="reference external" href="http://mercurial.selenic.com">Mercurial</a>.</p>
178<p>To get a copy of the sources, just <em>clone</em> the repository:</p>
[16]179<div class="highlight-python"><pre>hg clone https://bitbucket.org/codigo23/mailjam mailjam-repo</pre>
[13]180</div>
[16]181<p>Then, go inside the <em>mailjam-repo</em> directory and run:</p>
[13]182<div class="highlight-python"><pre>python setup.py install</pre>
183</div>
184<div class="admonition warning">
185<p class="first admonition-title">Warning</p>
186<p class="last">If you want to install it <em>system-wide</em>, probably you will need <em>root</em>
187privileges (check your OS documentation to learn more about how to get
188<em>root</em> privileges - for example using <a class="reference external" href="http://sudo.ws">sudo</a>)</p>
189</div>
190<div class="admonition note">
191<p class="first admonition-title">Note</p>
192<p class="last">This process will work inside a <a class="reference external" href="http://www.virtualenv.org/en/latest/index.html">virtualenv</a> too.</p>
193</div>
194</div>
195</div>
196</div>
[16]197<div class="section" id="setting-up-mailjam">
[27]198<span id="install-setting-up-mailjam"></span><h2><a class="toc-backref" href="#id18">Setting up Mailjam</a><a class="headerlink" href="#setting-up-mailjam" title="Permalink to this headline"></a></h2>
199<p>In order to setup Mailjam, you will have to create the needed
200<a class="reference internal" href="configuration.html"><em>configuration files</em></a>. Each component has its own
201configuration file:</p>
202<ul class="simple">
203<li>The <a class="reference internal" href="overview.html#overview-mailjam-daemon"><em>Mailjam daemon</em></a> configuration file is
204<a class="reference internal" href="configuration.html#configuration-daemon"><em>mailjam.conf</em></a></li>
205<li>The <a class="reference internal" href="overview.html#overview-mailjam-mta-client"><em>Mailjam MTA client</em></a> configuration
206file is <a class="reference internal" href="configuration.html#configuration-mta-client"><em>mailjam-mta.conf</em></a></li>
207<li>The <a class="reference internal" href="overview.html#overview-mailjam-cli-client"><em>Mailjam CLI client</em></a> configuration
208file is <a class="reference internal" href="configuration.html#configuration-cli-client"><em>mailjam-cli.conf</em></a></li>
209</ul>
210<p>Refer to each configuration file documentation to learn more about the different
211settings you can customize.</p>
212<p>Each component will search for its configuration file in a list of predefined
213locations, but you can override that behaviour using the <em>-c</em> parameter when
214starting the component.</p>
215<div class="admonition note">
216<p class="first admonition-title">Note</p>
217<p>Mailjam will search for the config files, in order, through the following
218paths:</p>
219<ol class="last arabic simple">
220<li>/etc/mailjam</li>
221<li>/etc</li>
222<li>/usr/local/etc/mailjam</li>
223<li>/usr/local/etc</li>
224<li>the <em>conf</em> directory within the sources (or the installed <em>egg</em> <a class="footnote-reference" href="#id8" id="id4">[4]</a>)</li>
225</ol>
226</div>
227<p>For example, you can start the <a class="reference internal" href="overview.html#overview-mailjam-daemon"><em>Mailjam daemon</em></a> passing
228<em>/var/db/mailjam/mailjam.conf</em> as its configuration file:</p>
229<div class="highlight-python"><div class="highlight"><pre><span class="n">mailjam</span><span class="o">-</span><span class="n">server</span> <span class="o">-</span><span class="n">c</span> <span class="o">/</span><span class="n">var</span><span class="o">/</span><span class="n">db</span><span class="o">/</span><span class="n">mailjam</span><span class="o">/</span><span class="n">mailjam</span><span class="o">.</span><span class="n">conf</span>
230</pre></div>
231</div>
232<div class="admonition-see-also admonition seealso">
233<p class="first admonition-title">See also</p>
234<p class="last"><a class="reference internal" href="running.html"><em>Running Mailjam</em></a> contains more information about how to run the different
235components.</p>
236</div>
237<p>If you have installed Mailjam using <a class="reference external" href="http://www.pip-installer.org/en/latest/index.html">pip</a>, <a class="reference external" href="http://peak.telecommunity.com/DevCenter/EasyInstall">easy_install</a> or even from sources,
238the setup process should have taken care of the configuration files, adding
239a copy of the default files included in the sources to the default
240destination.</p>
241<div class="admonition warning">
242<p class="first admonition-title">Warning</p>
243<p class="last">The default destination will be different based on your operating system.
244For example, in most linux servers it will copy the files to <em>/etc/mailjam</em>,
245while in BSD servers it will copy the files to <em>/usr/local/etc/mailjam</em>.</p>
246</div>
247<div class="admonition-see-also admonition seealso">
248<p class="first admonition-title">See also</p>
249<p class="last"><a class="reference internal" href="configuration.html"><em>Configuration files, settings and formats documentation</em></a></p>
250</div>
[13]251</div>
[16]252<div class="section" id="running-mailjam">
[27]253<span id="install-running-mailjam"></span><h2><a class="toc-backref" href="#id19">Running Mailjam</a><a class="headerlink" href="#running-mailjam" title="Permalink to this headline"></a></h2>
254<p>In order to run a full Mailjam environment, you will have to start the different
255components separately:</p>
256<ol class="arabic simple">
257<li><a class="reference internal" href="running.html#running-daemon"><em>Start the daemon</em></a></li>
258<li><a class="reference internal" href="running.html#running-cli-client"><em>Run the cli client and manage your mailing lists</em></a></li>
259<li><a class="reference internal" href="running.html#running-mta-client"><em>Add as much MTA clients as you need to your mail server</em></a></li>
260</ol>
261<p>The daemon will have to be running all the time (it is the component responsible
262for providing information to the clients). You will need the CLI client to add,
263edit or delete mailing lists and each MTA client will be responsible to handle
264incoming emails for each mailing list.</p>
[13]265</div>
266<div class="section" id="running-tests-developers-only">
[27]267<span id="install-running-tests"></span><h2><a class="toc-backref" href="#id20">Running tests (developers only)</a><a class="headerlink" href="#running-tests-developers-only" title="Permalink to this headline"></a></h2>
268<p>Just in case you were wondering, <strong>yes</strong>, Mailjam code has some tests you can
269run to check everything is ok and that the software should run smoothly on your
270server(s).</p>
271<p>To run the tests, simply get a copy of the sources from our public repository:</p>
272<div class="highlight-python"><pre>hg clone https://bitbucket.org/codigo23/mailjam mailjam-repo</pre>
273</div>
274<p>then run the tests:</p>
275<div class="highlight-python"><pre>cd mailjam-repo &amp;&amp; ./bin/run_tests</pre>
276</div>
277<table class="docutils footnote" frame="void" id="id5" rules="none">
[13]278<colgroup><col class="label" /><col /></colgroup>
279<tbody valign="top">
[27]280<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td><a class="reference external" href="http://docs.python.org/tutorial/modules.html#packages">http://docs.python.org/tutorial/modules.html#packages</a></td></tr>
281</tbody>
282</table>
283<table class="docutils footnote" frame="void" id="id6" rules="none">
284<colgroup><col class="label" /><col /></colgroup>
285<tbody valign="top">
286<tr><td class="label"><a class="fn-backref" href="#id3">[2]</a></td><td><a class="reference external" href="https://bitbucket.org/codigo23/mailjam">https://bitbucket.org/codigo23/mailjam</a></td></tr>
287</tbody>
288</table>
289<table class="docutils footnote" frame="void" id="id7" rules="none">
290<colgroup><col class="label" /><col /></colgroup>
291<tbody valign="top">
292<tr><td class="label"><a class="fn-backref" href="#id2">[3]</a></td><td><a class="reference external" href="http://pypi.python.org/pypi/mailjam">http://pypi.python.org/pypi/mailjam</a></td></tr>
293</tbody>
294</table>
295<table class="docutils footnote" frame="void" id="id8" rules="none">
296<colgroup><col class="label" /><col /></colgroup>
297<tbody valign="top">
298<tr><td class="label"><a class="fn-backref" href="#id4">[4]</a></td><td><a class="reference external" href="http://svn.python.org/projects/sandbox/trunk/setuptools/doc/formats.txt">http://svn.python.org/projects/sandbox/trunk/setuptools/doc/formats.txt</a></td></tr>
[13]299</tbody>
300</table>
301</div>
302</div>
303
304
305 </div>
306 </div>
307 </div>
308 <div class="sphinxsidebar">
309 <div class="sphinxsidebarwrapper">
310 <h3><a href="index.html">Table Of Contents</a></h3>
311 <ul>
312<li><a class="reference internal" href="#">Installation instructions</a><ul>
313<li><a class="reference internal" href="#first-install-dependencies">First, install dependencies</a></li>
[16]314<li><a class="reference internal" href="#second-install-mailjam">Second, install Mailjam</a><ul>
[13]315<li><a class="reference internal" href="#installing-using-pip">Installing using pip</a></li>
316<li><a class="reference internal" href="#installing-using-easy-install">Installing using easy_install</a></li>
317<li><a class="reference internal" href="#installing-inside-a-virtualenv">Installing inside a virtualenv</a></li>
318<li><a class="reference internal" href="#installing-from-sources">Installing from sources</a><ul>
319<li><a class="reference internal" href="#releases">Releases</a></li>
320<li><a class="reference internal" href="#from-repository">From repository</a></li>
321</ul>
322</li>
323</ul>
324</li>
[16]325<li><a class="reference internal" href="#setting-up-mailjam">Setting up Mailjam</a></li>
326<li><a class="reference internal" href="#running-mailjam">Running Mailjam</a></li>
[13]327<li><a class="reference internal" href="#running-tests-developers-only">Running tests (developers only)</a></li>
328</ul>
329</li>
330</ul>
331
332 <h4>Previous topic</h4>
333 <p class="topless"><a href="overview.html"
[16]334 title="previous chapter">Overview of mailjam&#8217;s architecture</a></p>
[13]335 <h4>Next topic</h4>
336 <p class="topless"><a href="configuration.html"
337 title="next chapter">Configuration</a></p>
338 <h3>This Page</h3>
339 <ul class="this-page-menu">
340 <li><a href="_sources/install.txt"
341 rel="nofollow">Show Source</a></li>
342 </ul>
343<div id="searchbox" style="display: none">
344 <h3>Quick search</h3>
345 <form class="search" action="search.html" method="get">
346 <input type="text" name="q" />
347 <input type="submit" value="Go" />
348 <input type="hidden" name="check_keywords" value="yes" />
349 <input type="hidden" name="area" value="default" />
350 </form>
351 <p class="searchtip" style="font-size: 90%">
352 Enter search terms or a module, class or function name.
353 </p>
354</div>
355<script type="text/javascript">$('#searchbox').show(0);</script>
356 </div>
357 </div>
358 <div class="clearer"></div>
359 </div>
360 <div class="related">
361 <h3>Navigation</h3>
362 <ul>
363 <li class="right" style="margin-right: 10px">
364 <a href="genindex.html" title="General Index"
365 >index</a></li>
366 <li class="right" >
367 <a href="configuration.html" title="Configuration"
368 >next</a> |</li>
369 <li class="right" >
[16]370 <a href="overview.html" title="Overview of mailjam’s architecture"
[13]371 >previous</a> |</li>
[16]372 <li><a href="index.html">Mailjam 0.1.0 documentation</a> &raquo;</li>
[13]373 </ul>
374 </div>
375 <div class="footer">
376 &copy; Copyright 2012, Soluciones Informaticas Codigo23 S.L.U..
377 Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.2.
378 </div>
379 </body>
380</html>
Note: See TracBrowser for help on using the repository browser.