diff --git a/doc/contributing/getting_started.rst b/doc/contributing/getting_started.rst index 695e65960..f45b65f07 100644 --- a/doc/contributing/getting_started.rst +++ b/doc/contributing/getting_started.rst @@ -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 `_ 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 `_ 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 `, 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 $ modoboa-admin.py deploy --dburl default: --domain localhost --devel instance @@ -69,12 +64,17 @@ ready to deploy a test instance:: You're ready to go! You should be able to access Modoboa at ``http://localhost:8000`` using ``admin:password`` as credentials. -Manage static files -=================== +Frontend +======== -Modoboa uses `bower `_ (thanks to `django-bower -`_) to manage its CSS and -javascript dependencies. +Legacy interface +---------------- + +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 `_ is used to manage the CSS and JavaScript +dependencies - i.e. Boostrap, jQuery - thanks to `django-bower +`_. Those dependencies are listed in a file called :file:`dev_settings.py` located inside the :file:`/modoboa/core` @@ -88,41 +88,59 @@ If you want to add a new dependency, just complete the It will download and store the required files into the :file:`/modoboa/bower_components` directory. -Test your modifications -======================= +New Vue.js interface +-------------------- -If you deployed a specific instance for your development needs, you -can run the tests suite as follows: +The 2.0 version of Modoboa introduces a completely new interface written +with the `Vue.js `_ framework. The source files are +located in the :file:`frontend/` directory. -.. sourcecode:: bash +To set it up, you will need to install NodeJS and Yarn - to manage the +dependencies. Then, navigate to the :file:`frontend/` directory and run:: - > python manage.py test modoboa.core modoboa.lib modoboa.admin modoboa.limits modoboa.relaydomains + $ yarn install -Otherwise, you can run the tests suite from the repository using `tox -`_. +You can now build it and serve it - while running your instance too to +serve the API - with:: -Start a basic Modoboa instance -============================== + $ yarn serve -From the repository, run the following command to launch a simple -instance with a few fixtures: +Tests +===== -.. sourcecode:: bash +If you deployed an instance for development, you can launch the tests +from it with:: - > tox -e serve + $ python manage.py test modoboa -You can use admin/password to log in. +You could also test just some them, i.e.:: -Build the documentation -======================= + $ python manage.py test modoboa.core.tests.test_authentication -If you need to modify the documenation and want to see the result, you -can build it as follows: +Alternatively, you can use `tox `_ from +the repository to run all the tests and check the coverage with:: -.. sourcecode:: bash + $ tox - > tox -e doc - > firefox .tox/doc/tmp/html/index.html +You could limit the environment to a specific Python version with the +``-e py`` 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 `_. + +To build it and see the result, run:: + + $ tox -e doc + $ open .tox/doc/tmp/html/index.html FAQ === diff --git a/doc/manual_installation/modoboa.rst b/doc/manual_installation/modoboa.rst index f939d3d21..156ace9a9 100644 --- a/doc/manual_installation/modoboa.rst +++ b/doc/manual_installation/modoboa.rst @@ -144,6 +144,8 @@ database owned by a ``modoboa`` user, run the following SQL commands: CREATE USER 'modoboa'@'localhost' IDENTIFIED BY 'my-strong-password-here'; GRANT ALL PRIVILEGES ON modoboa.* TO 'modoboa'@'localhost'; +.. _deployment: + Deploy an instance ------------------ diff --git a/doc/manual_installation/webserver.rst b/doc/manual_installation/webserver.rst index 947193577..42d5798db 100644 --- a/doc/manual_installation/webserver.rst +++ b/doc/manual_installation/webserver.rst @@ -128,17 +128,6 @@ following configuration:: autoindex on; } - location ^~ /new-admin { - alias /frontend/; - index index.html; - - expires -1; - add_header Pragma "no-cache"; - add_header Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"; - - try_files $uri $uri/ /index.html = 404; - } - location / { proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header Host $http_host; diff --git a/doc/upgrade.rst b/doc/upgrade.rst index 9a39d82af..b2ae9ff3a 100644 --- a/doc/upgrade.rst +++ b/doc/upgrade.rst @@ -94,12 +94,8 @@ Specific instructions 2.0.0-beta.1 ============ -First beta release of the 2.0 which brings a new admin interface and a -new version of the API. - -Add the two following items: ``drf_spectacular`` and -``phonenumber_field`` to ``INSTALLED_APPS`` in the :file:`settings.py` -file, as follows: +Add ``drf_spectacular`` and ``phonenumber_field`` to ``INSTALLED_APPS`` +in the :file:`settings.py` file, as follows: .. sourcecode:: python @@ -149,11 +145,16 @@ Add the new following settings: PHONENUMBER_DB_FORMAT = 'INTERNATIONAL' -To use the new interface, you need to update the configuration of your -web server. See the example for :ref:`nginx `. +New admin interface +------------------- -Then, copy the frontend files in the folder you specified in your web -server configuration. If you used the installer, the folder should be +This new release brings a new admin interface written with Vue.js framework. +It is a work in progress and all features are not yet implemented - i.e. +extensions integration - but you could give it a try. It uses a new API +version but the old one is still available. + +You will need to copy the frontend files in the folder you specified in your +web server configuration. If you used the installer, the folder should be ``/srv/modoboa/instance/frontend``: .. sourcecode:: bash @@ -161,8 +162,8 @@ server configuration. If you used the installer, the folder should be mkdir /srv/modoboa/instance/frontend cp -r /srv/modoboa/env/lib/pythonX.X/site-packages/frontend/dist/* /srv/modoboa/instance/frontend -Finally, edit the :file:`/srv/modoboa/instance/frontend/config.json` -and update the ``API_BASE_URL`` setting according to the hostname of your server:: +Then, edit the :file:`/srv/modoboa/instance/frontend/config.json` +and update the ``API_BASE_URL`` setting according to the hostname of your server: .. sourcecode:: json @@ -170,6 +171,22 @@ and update the ``API_BASE_URL`` setting according to the hostname of your server "API_BASE_URL": "https:///api/v2" } +Finally, update the configuration of your web server to serve the frontend +files. For NGINX, you should add the following in the ``server`` block: + +.. sourcecode:: nginx + + location ^~ /new-admin { + alias /srv/modoboa/instance/frontend/; + index index.html; + + expires -1; + add_header Pragma "no-cache"; + add_header Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"; + + try_files $uri $uri/ /index.html = 404; + } + 1.17.0 ====== diff --git a/modoboa/core/templates/core/dashboard.html b/modoboa/core/templates/core/dashboard.html index 6169b6341..ae96a0ad6 100644 --- a/modoboa/core/templates/core/dashboard.html +++ b/modoboa/core/templates/core/dashboard.html @@ -5,10 +5,12 @@ {% block pagetitle %}{% trans "Dashboard" %}{% endblock %} {% block container_content %} + {% if user.is_admin %}
Want to check the new admin interface? Go to Modoboa v2
+ {% endif %}