mirror of
https://github.com/jwinterm/modoboa.git
synced 2026-10-17 05:41:25 +02:00
150 lines
4.1 KiB
Markdown
150 lines
4.1 KiB
Markdown
---
|
|
title: Getting stated with modoboa
|
|
description: Discover how to develop and extend modoboa
|
|
head:
|
|
- - meta
|
|
- name: 'keywords'
|
|
content: 'modoboa, getting started, backend, frontend, docker'
|
|
---
|
|
|
|
# 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.
|
|
|
|
## With Docker
|
|
|
|
A docker image is available for developers.
|
|
|
|
To use it, you must install docker and docker-compose
|
|
|
|
* [docker](https://docs.docker.com/install/) and
|
|
* [docker-compose](https://docs.docker.com/compose/install/) first.
|
|
|
|
If not already done, clone the repo and open it:
|
|
|
|
```shell
|
|
$ git clone https://github.com/modoboa/modoboa.git
|
|
$ cd modoboa
|
|
```
|
|
|
|
Then, just run the following command:
|
|
|
|
```shell
|
|
$ docker-compose up
|
|
```
|
|
|
|
Then if not done already, run this command to create an OIDC application in order to be able to log in from the frontend:
|
|
|
|
``` bash
|
|
$ docker exec modoboa-api '/bin/sh -c python3 /code/test_project/manage.py createapplication --name frontend --client-id "LVQbfIIX3khWR3nDvix1u9yEGHZUxcx53bhJ7FlD" --user 1 --algorithm RS256 --redirect-uris 'https://localhost:3000/login/logged' public authorization-code'
|
|
$ docker exec modoboa-api '/bin/sh -c python3 /code/test_project/manage.py createapplication --name Dovecot --skip-authorization --client-id=dovecot --client-secret=Toto12345 confidential client-credentials'
|
|
```
|
|
|
|
It will start the docker environment and make a Modoboa instance available at `https://localhost:8000`
|
|
and the new admin interface at `https://localhost:3000`.
|
|
|
|
If you don't want to use docker or need a more complex development setup, go to the next section.
|
|
|
|
## Without Docker
|
|
|
|
### 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:
|
|
|
|
```shell
|
|
$ python3 -m venv <path>
|
|
$ source <path>/bin/activate
|
|
$ git clone https://github.com/modoboa/modoboa.git
|
|
$ cd modoboa
|
|
$ pip install -e .[dev]
|
|
```
|
|
|
|
This will create 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 `create a database <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:
|
|
|
|
```shell
|
|
$ 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.
|
|
|
|
## Frontend
|
|
|
|
The 2.0 version of Modoboa introduces a completely new interface written with the [Vue.js](https://vuejs.org/) framework.
|
|
|
|
The source files are located in the `frontend/`{.interpreted-text role="file"} directory.
|
|
|
|
To set it up, you will need to install NodeJS and Yarn - to manage the
|
|
dependencies.
|
|
|
|
Then, navigate to the `frontend/` directory and run:
|
|
|
|
```shell
|
|
$ yarn install
|
|
```
|
|
|
|
You can now build it and serve it - while running your instance too to
|
|
serve the API - with:
|
|
|
|
```shell
|
|
$ yarn serve
|
|
```
|
|
|
|
## Tests
|
|
|
|
If you deployed an instance for development, you can launch the tests from it with:
|
|
|
|
```shell
|
|
$ python manage.py test modoboa
|
|
```
|
|
|
|
You could also test just some them, i.e.:
|
|
|
|
```shell
|
|
$ python manage.py test modoboa.core.tests.test_authentication
|
|
```
|
|
|
|
Alternatively, you can use [tox](https://tox.readthedocs.io)
|
|
from the repository to run all the tests and check the coverage with:
|
|
|
|
```shell
|
|
$ tox
|
|
```
|
|
|
|
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:
|
|
|
|
```shell
|
|
$ tox -e serve
|
|
```
|
|
|
|
## Documentation
|
|
|
|
The source files are located in the `/doc-ng/`[ folder and are
|
|
written in markdown.
|
|
|
|
They are formatted in HTML and compiled thanks to VitePress
|
|
|
|
To build it and see the result, run:
|
|
|
|
```shell
|
|
$ npm run dev
|
|
``` |