<NME> getting_started.rst
<BEF> ###########
Useful tips
###########

You would like to work on Modoboa but you don't know where to start?
You're at the right place! Browse this page to learn useful tips.

Docker
======

A docker image is available for developers. To use it, you must
install `docker <https://docs.docker.com/install/>`_ and
`docker-compose <https://docs.docker.com/compose/install/>`_ first.

Then, just run the following command::

  $ docker-compose up

It will start the docker environment and make a Modoboa instance
available at ``http://localhost:8000``.

If you don't want to use docker or need a more complex development
setup, go to the next section.

.. _venv_for_dev:

Prerequisites For Development
=============================
If you encounter errors about missing tools, please ensure you have them installed with the foollowing:

   $ sudo apt install librrd-dev

Prepare a virtual environment
=============================

A `virtual environment
<https://docs.python.org/fr/3/library/venv.html>`_ is a good way to
setup a development environment on your machine.

To do so, run the following commands::

  $ python3 -m venv <path>
  $ source <path>/bin/activate
  $ git clone https://github.com/modoboa/modoboa.git
  $ cd modoboa
  $ python setup.py develop
  $ pip install -r dev-requirements.txt

The ``develop`` command creates a symbolic link to your local copy so
any modification you make will be automatically available in your
environment, no need to copy them.

Deploy an instance for development
==================================

.. warning::

   Make sure to :ref:`create a database <database>` before running
   this step. The format of the database url is also described in this
   page.

Now that you have a :ref:`running environment <venv_for_dev>`, you're
ready to deploy a test instance::

  $ cd <path>
  $ modoboa-admin.py deploy --dburl default:<database url> --domain localhost --devel instance
  $ python manage.py runserver

You're ready to go! You should be able to access Modoboa at
``http://localhost:8000`` using ``admin:password`` as credentials.

Manage static files
===================

Modoboa uses `bower <http://bower.io/>`_ (thanks to `django-bower
<https://github.com/nvbn/django-bower>`_) to manage its CSS and

The Django templates and views are used to render this interface, which
is served by the uWSGI application - or the local server in development.
`bower <http://bower.io/>`_  is used to manage the CSS and JavaScript
dependencies - i.e. Boostrap, jQuery - thanks to `django-bower
<https://github.com/nvbn/django-bower>`_.

Those dependencies are listed in a file called :file:`dev_settings.py`
located inside the :file:`<path_to_local_copy>/modoboa/core`
directory.

It will download and store the required files into the
:file:`<path_to_local_copy>/modoboa/bower_components` directory.

Test your modifications
=======================

If you deployed a specific instance for your development needs, you
can run the tests suite as follows:

.. sourcecode:: bash

  > python manage.py test modoboa.core modoboa.lib modoboa.admin modoboa.limits modoboa.relaydomains

Otherwise, you can run the tests suite from the repository using `tox
<https://tox.readthedocs.io>`_.

Start a basic Modoboa instance
==============================

From the repository, run the following command to launch a simple
instance with a few fixtures:

.. sourcecode:: bash

  > tox -e serve

You can use admin/password to log in.

Build the documentation
=======================

If you need to modify the documenation and want to see the result, you
can build it as follows:

.. sourcecode:: bash

   > tox -e doc
   > firefox .tox/doc/tmp/html/index.html

FAQ
===
You could limit the environment to a specific Python version with the
``-e py<version>`` argument.

Note that it is also possible to quickly run a test instance without
any deployment - e.g. to preview some changes - by running::

  $ tox -e serve

Documentation
=============

The source files are located in the file:`doc/` folder and are written
in reStructuredText (reST). They are formatted in HTML and compiled
thanks to `Sphinx <https://www.sphinx-doc.org/en/master/>`_.

To build it and see the result, run::

  $ tox -e doc
  $ open .tox/doc/tmp/html/index.html

FAQ
===

bower command is missing in manage.py
-------------------------------------

*bower* command is missing in *manage.py* if you don't use the
``--devel`` option of the ``modoboa-admin.py deploy`` command.

To fix it, regenerate your instance or update your ``settings.py``
file manually. Look at ``devmode`` in
https://github.com/tonioo/modoboa/blob/master/modoboa/core/commands/templates/settings.py.tpl

<MSG> Reorganise the getting started to dev doc

<DFF> @@ -1,12 +1,12 @@
-###########
-Useful tips
-###########
+###############
+Getting started
+###############
 
 You would like to work on Modoboa but you don't know where to start?
 You're at the right place! Browse this page to learn useful tips.
 
-Docker
-======
+With Docker
+===========
 
 A docker image is available for developers. To use it, you must
 install `docker <https://docs.docker.com/install/>`_ and
@@ -22,16 +22,11 @@ available at ``http://localhost:8000``.
 If you don't want to use docker or need a more complex development
 setup, go to the next section.
 
-.. _venv_for_dev:
-
-Prerequisites For Development
-=============================
-If you encounter errors about missing tools, please ensure you have them installed with the foollowing:
-
-   $ sudo apt install librrd-dev
+Without Docker
+==============
 
 Prepare a virtual environment
-=============================
+-----------------------------
 
 A `virtual environment
 <https://docs.python.org/fr/3/library/venv.html>`_ is a good way to
@@ -51,7 +46,7 @@ any modification you make will be automatically available in your
 environment, no need to copy them.
 
 Deploy an instance for development
-==================================
+----------------------------------
 
 .. warning::
 
@@ -59,8 +54,8 @@ Deploy an instance for development
    this step. The format of the database url is also described in this
    page.
 
-Now that you have a :ref:`running environment <venv_for_dev>`, you're
-ready to deploy a test instance::
+Now that you have setup a development environment, you can deploy a
+test instance and run it::
 
   $ cd <path>
   $ modoboa-admin.py deploy --dburl default:<database url> --domain localhost --devel instance
@@ -70,7 +65,7 @@ You're ready to go! You should be able to access Modoboa at
 ``http://localhost:8000`` using ``admin:password`` as credentials.
 
 Manage static files
-===================
+-------------------
 
 Modoboa uses `bower <http://bower.io/>`_ (thanks to `django-bower
 <https://github.com/nvbn/django-bower>`_) to manage its CSS and
@@ -88,41 +83,42 @@ If you want to add a new dependency, just complete the
 It will download and store the required files into the
 :file:`<path_to_local_copy>/modoboa/bower_components` directory.
 
-Test your modifications
-=======================
+Tests
+=====
 
-If you deployed a specific instance for your development needs, you
-can run the tests suite as follows:
+If you deployed an instance for development, you can launch the tests
+from it with::
 
-.. sourcecode:: bash
+  $ python manage.py test modoboa
 
-  > python manage.py test modoboa.core modoboa.lib modoboa.admin modoboa.limits modoboa.relaydomains
+You could also test just some them, i.e.::
 
-Otherwise, you can run the tests suite from the repository using `tox
-<https://tox.readthedocs.io>`_.
+  $ python manage.py test modoboa.core.tests.test_authentication
 
-Start a basic Modoboa instance
-==============================
+Alternatively, you can use `tox <https://tox.readthedocs.io>`_ from
+the repository to run all the tests and check the coverage with::
 
-From the repository, run the following command to launch a simple
-instance with a few fixtures:
+  $ tox
 
-.. sourcecode:: bash
+You could limit the environment to a specific Python version with the
+``-e py<version>`` argument.
 
-  > tox -e serve
+Note that it is also possible to quickly run a test instance without
+any deployment - e.g. to preview some changes - by running::
 
-You can use admin/password to log in.
+  $ tox -e serve
 
-Build the documentation
-=======================
+Documentation
+=============
 
-If you need to modify the documenation and want to see the result, you
-can build it as follows:
+The source files are located in the ``doc/`` folder and are written
+in reStructuredText (reST). They are formatted in HTML and compiled
+thanks to `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
 
-.. sourcecode:: bash
+To build it and see the result, run::
 
-   > tox -e doc
-   > firefox .tox/doc/tmp/html/index.html
+  $ tox -e doc
+  $ open .tox/doc/tmp/html/index.html
 
 FAQ
 ===

Reorganise the getting started to dev doc