From ea711a6be702362fed8135a3560e0ce8325a47c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Lebleu?= Date: Mon, 12 Jul 2021 11:02:15 +0200 Subject: [PATCH 1/5] Show new admin banner to admins only --- modoboa/core/templates/core/dashboard.html | 2 ++ 1 file changed, 2 insertions(+) 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 %}
From 589f0a5c474139a19b635829624a4984890fcddb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Lebleu?= Date: Mon, 12 Jul 2021 11:29:55 +0200 Subject: [PATCH 2/5] Add a subsection for new admin in Upgrade doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit … and inform that it is a work in progress. This also removes the partial configuration of web servers for the new admin. --- doc/manual_installation/webserver.rst | 11 ------- doc/upgrade.rst | 41 +++++++++++++++++++-------- 2 files changed, 29 insertions(+), 23 deletions(-) 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 ====== From 79801eb309e5628f2dfff631d35aad672630f89a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Lebleu?= Date: Mon, 12 Jul 2021 12:22:49 +0200 Subject: [PATCH 3/5] Reorganise the getting started to dev doc --- doc/contributing/getting_started.rst | 74 +++++++++++++--------------- 1 file changed, 35 insertions(+), 39 deletions(-) diff --git a/doc/contributing/getting_started.rst b/doc/contributing/getting_started.rst index 695e65960..c86145069 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 @@ -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 `_ (thanks to `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:`/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 -`_. + $ python manage.py test modoboa.core.tests.test_authentication -Start a basic Modoboa instance -============================== +Alternatively, you can use `tox `_ 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`` 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 `_. -.. 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 === From 9910b86630d845cd4107ea54f77ab35409724da6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Lebleu?= Date: Mon, 12 Jul 2021 12:28:00 +0200 Subject: [PATCH 4/5] Add missing deployment label in doc --- doc/manual_installation/modoboa.rst | 2 ++ 1 file changed, 2 insertions(+) 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 ------------------ From 85ed142bc1c6468c2b4d1cec254a0358288d253c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Lebleu?= Date: Mon, 12 Jul 2021 16:44:13 +0200 Subject: [PATCH 5/5] Document how to set up the new interface --- doc/contributing/getting_started.rst | 34 +++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/doc/contributing/getting_started.rst b/doc/contributing/getting_started.rst index c86145069..f45b65f07 100644 --- a/doc/contributing/getting_started.rst +++ b/doc/contributing/getting_started.rst @@ -64,12 +64,17 @@ test instance and run it:: 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` @@ -83,6 +88,23 @@ 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. +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 :file:`frontend/` directory. + +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:: + + $ yarn install + +You can now build it and serve it - while running your instance too to +serve the API - with:: + + $ yarn serve + Tests ===== @@ -111,7 +133,7 @@ any deployment - e.g. to preview some changes - by running:: Documentation ============= -The source files are located in the ``doc/`` folder and are written +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 `_.