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.
Then, just run the following command:
$ docker-compose up
It will start the docker environment and make a Modoboa instance
http://localhost:8000 and the new admin interface at
If you don’t want to use docker or need a more complex development setup, go to the next section.
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 https://github.com/modoboa/modoboa.git
$ cd modoboa
$ python setup.py develop
$ pip install -r dev-requirements.txt
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 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
$ python manage.py runserver
You’re ready to go! You should be able to access Modoboa at
admin:password as credentials.
Those dependencies are listed in a file called
located inside the
If you want to add a new dependency, just complete the
BOWER_INSTALLED_APPS parameter and run the following command:
$ python manage.py bower install
It will download and store the required files into the
Don’t forget to regenerate the localization files when you add strings. See the translation page
New Vue.js interface¶
The 2.0 version of Modoboa introduces a completely new interface written
with the Vue.js framework. The source files are
located in the
To set it up, you will need to install NodeJS and Yarn - to manage the
dependencies. Then, navigate to the
frontend/ directory and run:
$ yarn install
You can now build it and serve it - while running your instance too to serve the API - with:
$ yarn serve
If you deployed an instance for development, you can launch the tests from it with:
$ python manage.py test modoboa
You could also test just some them, i.e.:
$ python manage.py test modoboa.core.tests.test_authentication
Alternatively, you can use tox from the repository to run all the tests and check the coverage with:
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
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.
To build it and see the result, run:
$ tox -e doc
$ open .tox/doc/tmp/html/index.html
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
file manually. Look at