Ignore:
Timestamp:
May 23, 2012, 6:32:54 PM (13 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:
1 edited

Legend:

Unmodified
Added
Removed

  • docs/src/_build/html/install.html

    r16 r27  
    5353           
    5454  <div class="section" id="installation-instructions">
    55 <h1><a class="toc-backref" href="#id3">Installation instructions</a><a class="headerlink" href="#installation-instructions" title="Permalink to this headline">¶</a></h1>
     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>
    5662<div class="contents topic" id="contents">
    5763<p class="topic-title first">Contents</p>
    5864<ul class="simple">
    59 <li><a class="reference internal" href="#installation-instructions" id="id3">Installation instructions</a><ul>
    60 <li><a class="reference internal" href="#first-install-dependencies" id="id4">First, install dependencies</a></li>
    61 <li><a class="reference internal" href="#second-install-mailjam" id="id5">Second, install Mailjam</a><ul>
    62 <li><a class="reference internal" href="#installing-using-pip" id="id6">Installing using pip</a></li>
    63 <li><a class="reference internal" href="#installing-using-easy-install" id="id7">Installing using easy_install</a></li>
    64 <li><a class="reference internal" href="#installing-inside-a-virtualenv" id="id8">Installing inside a virtualenv</a></li>
    65 <li><a class="reference internal" href="#installing-from-sources" id="id9">Installing from sources</a><ul>
    66 <li><a class="reference internal" href="#releases" id="id10">Releases</a></li>
    67 <li><a class="reference internal" href="#from-repository" id="id11">From repository</a></li>
    68 </ul>
    69 </li>
    70 </ul>
    71 </li>
    72 <li><a class="reference internal" href="#setting-up-mailjam" id="id12">Setting up Mailjam</a></li>
    73 <li><a class="reference internal" href="#running-mailjam" id="id13">Running Mailjam</a></li>
    74 <li><a class="reference internal" href="#running-tests-developers-only" id="id14">Running tests (developers only)</a></li>
     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>
     74</ul>
     75</li>
     76</ul>
     77</li>
     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>
    7581</ul>
    7682</li>
    … …  
    7884</div>
    7985<div class="section" id="first-install-dependencies">
    80 <span id="install-dependencies"></span><h2><a class="toc-backref" href="#id4">First, install dependencies</a><a class="headerlink" href="#first-install-dependencies" title="Permalink to this headline">¶</a></h2>
     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>
    8187<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>
    8288<p>Mailjam has been tested with python <em>2.7.x</em>, but it should work with versions
    8389<em>2.6.x</em> too.</p>
    84 <p>Please, refer to your operating system package system documentation to learn
    85 more about how to install python.</p>
     90<p>Please, refer to your operating system documentation to learn more about how
     91to install python.</p>
    8692</div>
    8793<div class="section" id="second-install-mailjam">
    88 <span id="install-mailjam"></span><h2><a class="toc-backref" href="#id5">Second, install Mailjam</a><a class="headerlink" href="#second-install-mailjam" title="Permalink to this headline">¶</a></h2>
     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>
    8998<div class="section" id="installing-using-pip">
    90 <span id="install-with-pip"></span><h3><a class="toc-backref" href="#id6">Installing using pip</a><a class="headerlink" href="#installing-using-pip" title="Permalink to this headline">¶</a></h3>
     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>
    91100<p>You can install Mailjam using <a class="reference external" href="http://www.pip-installer.org/en/latest/index.html">pip</a>:</p>
    92 <div class="highlight-python"><pre>pip install -e https://bitbucket.org/codigo23/mailjam#egg=mailjam</pre>
    93 </div>
    94 <div class="admonition note">
    95 <p class="first admonition-title">Note</p>
    96 <p class="last">Mailjam has not been recorded/uploaded to <a class="reference external" href="http://pypi.python.org/pypi">pypi</a> yet, so, in order to install
    97 it using pip you will have to provide the URL for the public Mailjam repo.</p>
     101<div class="highlight-python"><pre>pip install Mailjam</pre>
     102</div>
     103<div class="admonition note">
     104<p class="first admonition-title">Note</p>
     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>
    98110</div>
    99111</div>
    100112<div class="section" id="installing-using-easy-install">
    101 <span id="install-with-easy-install"></span><h3><a class="toc-backref" href="#id7">Installing using easy_install</a><a class="headerlink" href="#installing-using-easy-install" title="Permalink to this headline">¶</a></h3>
    102 <p>You can not install Mailjam using <a class="reference external" href="http://peak.telecommunity.com/DevCenter/EasyInstall">easy_install</a> yet (until we do record/upload
    103 it to pypi)</p>
     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>
    104117</div>
    105118<div class="section" id="installing-inside-a-virtualenv">
    106 <span id="install-inside-virtualenv"></span><h3><a class="toc-backref" href="#id8">Installing inside a virtualenv</a><a class="headerlink" href="#installing-inside-a-virtualenv" title="Permalink to this headline">¶</a></h3>
     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>
    107120<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>
    108121<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>
    … …  
    122135</div>
    123136<p>And, once the environment has been activated, use pip to install Mailjam:</p>
    124 <div class="highlight-python"><pre>env$ pip install -e https://bitbucket.org/codigo23/mailjam#egg=mailjam</pre>
     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>
    125145</div>
    126146</div>
    127147<div class="section" id="installing-from-sources">
    128 <span id="install-from-sources"></span><h3><a class="toc-backref" href="#id9">Installing from sources</a><a class="headerlink" href="#installing-from-sources" title="Permalink to this headline">¶</a></h3>
     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>
    129149<p>When installing from sources, you can download one of the official releases
    130150or you can go with the <em>bleeding edge</em> and get a copy of the official source
    131151code repository.</p>
    132152<div class="section" id="releases">
    133 <span id="install-from-release"></span><h4><a class="toc-backref" href="#id10">Releases</a><a class="headerlink" href="#releases" title="Permalink to this headline">¶</a></h4>
    134 <p><strong>There are no releases yet</strong>. You will have to install it from the repository.</p>
    135 </div>
    136 <div class="section" id="from-repository">
    137 <span id="install-from-repository"></span><h4><a class="toc-backref" href="#id11">From repository</a><a class="headerlink" href="#from-repository" title="Permalink to this headline">¶</a></h4>
    138 <p>The source code of Mailjam is hosted in <a class="reference external" href="https://bitbucket.org">bitbucket</a> <a class="footnote-reference" href="#id2" id="id1">[1]</a>. In order to grab
    139 the latest sources you need <a class="reference external" href="http://mercurial.selenic.com">Mercurial</a>.</p>
    140 <p>To get a copy of the sources, just <em>clone</em> the repository:</p>
    141 <div class="highlight-python"><pre>hg clone https://bitbucket.org/codigo23/mailjam mailjam-repo</pre>
    142 </div>
    143 <p>Then, go inside the <em>mailjam-repo</em> directory and run:</p>
     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>
    144161<div class="highlight-python"><pre>python setup.py install</pre>
    145162</div>
    … …  
    155172</div>
    156173</div>
     174<div class="section" id="from-repository">
     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
     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>
     179<div class="highlight-python"><pre>hg clone https://bitbucket.org/codigo23/mailjam mailjam-repo</pre>
     180</div>
     181<p>Then, go inside the <em>mailjam-repo</em> directory and run:</p>
     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>
    157195</div>
    158196</div>
    159197<div class="section" id="setting-up-mailjam">
    160 <span id="install-setting-up-mailjam"></span><h2><a class="toc-backref" href="#id12">Setting up Mailjam</a><a class="headerlink" href="#setting-up-mailjam" title="Permalink to this headline">¶</a></h2>
    161 <p>TBW</p>
     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>
    162251</div>
    163252<div class="section" id="running-mailjam">
    164 <span id="install-running-mailjam"></span><h2><a class="toc-backref" href="#id13">Running Mailjam</a><a class="headerlink" href="#running-mailjam" title="Permalink to this headline">¶</a></h2>
    165 <p>TBW</p>
     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>
    166265</div>
    167266<div class="section" id="running-tests-developers-only">
    168 <span id="install-running-tests"></span><h2><a class="toc-backref" href="#id14">Running tests (developers only)</a><a class="headerlink" href="#running-tests-developers-only" title="Permalink to this headline">¶</a></h2>
    169 <p>TBW</p>
    170 <table class="docutils footnote" frame="void" id="id2" rules="none">
     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">
    171278<colgroup><col class="label" /><col /></colgroup>
    172279<tbody valign="top">
    173 <tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td><a class="reference external" href="https://bitbucket.org/codigo23/mailjam">https://bitbucket.org/codigo23/mailjam</a></td></tr>
     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>
    174299</tbody>
    175300</table>
Note: See TracChangeset for help on using the changeset viewer.