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.


A docker image is available for developers. To use it, you must install docker and docker-compose 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.

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 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
$ cd modoboa
$ python 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


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

Now that you have a running environment, you’re ready to deploy a test instance:

$ cd <path>
$ deploy --dburl default:<database url> --domain localhost --devel instance
$ python 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 (thanks to django-bower) to manage its CSS and javascript dependencies.

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

If you want to add a new dependency, just complete the BOWER_INSTALLED_APPS parameter and run the following command:

$ python bower install

It will download and store the required files into the <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:

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

Otherwise, you can run the tests suite from the repository using tox.

Start a basic Modoboa instance

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

> 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:

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


bower command is missing in

bower command is missing in if you don’t use the --devel option of the deploy command.

To fix it, regenerate your instance or update your file manually. Look at devmode in