Merge pull request #2318 from jeromelebleu/new-admin

Some documentation and fix for the new interface

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 <https://docs.docker.com/install/>`_ 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
 <https://docs.python.org/fr/3/library/venv.html>`_ 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 <venv_for_dev>`, 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 <path>
   $ modoboa-admin.py deploy --dburl default:<database url> --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 <http://bower.io/>`_ (thanks to `django-bower
-<https://github.com/nvbn/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 <http://bower.io/>`_  is used to manage the CSS and JavaScript
+dependencies - i.e. Boostrap, jQuery - thanks to `django-bower
+<https://github.com/nvbn/django-bower>`_.
 
 Those dependencies are listed in a file called :file:`dev_settings.py`
 located inside the :file:`<path_to_local_copy>/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:`<path_to_local_copy>/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 <https://vuejs.org/>`_ 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
-<https://tox.readthedocs.io>`_.
+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 <https://tox.readthedocs.io>`_ 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<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
+
+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 <https://www.sphinx-doc.org/en/master/>`_.
+
+To build it and see the result, run::
+
+  $ tox -e doc
+  $ open .tox/doc/tmp/html/index.html
 
 FAQ
 ===

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

doc/manual_installation/webserver.rst

@@ -128,17 +128,6 @@ following configuration::
                 autoindex on;
         }
 
-        location ^~ /new-admin {
-                alias  <modoboa_instance_path>/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;

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 <nginx_label>`.
+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://<hostname of your server>/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
 ======
 

modoboa/core/templates/core/dashboard.html

@@ -5,10 +5,12 @@
 {% block pagetitle %}{% trans "Dashboard" %}{% endblock %}
 
 {% block container_content %}
+  {% if user.is_admin %}
   <div class="alert alert-warning text-center">
     <strong>Want to check the new admin interface?</strong>
     <a class="btn btn-default" style="margin-left: 20px;" href="/new-admin" target="_blank">Go to Modoboa v2</a>
   </div>
+  {% endif %}
 
   <div class="row">
     <div class="col-xs-12 col-sm-offset-1 col-sm-10">