Merge branch 'develop'

.gitignore

@@ -3,7 +3,6 @@ venv
 */venv
 **/*.pyc
 *.cache
-assets
 webpack-stats.*
 .vscode
 *.sqlite3

Dockerfile

@@ -15,12 +15,13 @@ COPY manager/requirements.txt .
 RUN pip install -r requirements.txt
 
 # Copy source code and build project
-COPY manager .
+COPY manager ./manager
+WORKDIR /usr/src/love/manager
 RUN find . | grep -E "(__pycache__|\.pyc|\.pyo$)" | xargs rm -rf
 RUN python manage.py collectstatic --noinput
 
 # Expose static files and port
-VOLUME /usr/src/love/static
+VOLUME /usr/src/love/manager/static
 EXPOSE 8000
 
 # Set env variables for runtime (to be replaced in docker-cpomse files)

Dockerfile-dev

@@ -23,4 +23,5 @@ ENV USER_USER_PASS=test
 ENV CMD_USER_PASS=test
 
 # Run development server in runtime
+WORKDIR /usr/src/love/manager
 CMD ["./runserver-dev.sh"]

Jenkinsfile

@@ -12,6 +12,8 @@ pipeline {
         anyOf {
           branch "master"
           branch "develop"
+          branch "bugfix/*"
+          branch "hotfix/*"
           branch "release/*"
         }
       }
@@ -24,7 +26,7 @@ pipeline {
           if (slashPosition > 0) {
             git_tag = git_branch.substring(slashPosition + 1, git_branch.length())
             git_branch = git_branch.substring(0, slashPosition)
-            if (git_branch == "release") {
+            if (git_branch == "release" || git_branch == "hotfix" || git_branch == "bugfix") {
               image_tag = git_tag
             }
           }
@@ -40,6 +42,8 @@ pipeline {
         anyOf {
           branch "master"
           branch "develop"
+          branch "bugfix/*"
+          branch "hotfix/*"
           branch "release/*"
         }
       }
@@ -54,6 +58,8 @@ pipeline {
         anyOf {
           branch "master"
           branch "develop"
+          branch "bugfix/*"
+          branch "hotfix/*"
           branch "release/*"
         }
       }

README.md

@@ -1,5 +1,44 @@
-# LOVE Manager
-
 This repository contains the code of the Django Channels project that acts as middleware for the LOVE-frontend
 
 See the documentation here: https://lsst-ts.github.io/LOVE-manager/html/index.html
+
+# Use as part of the LOVE system
+In order to use the LOVE-manager as part of the LOVE system we recommend to use the docker-compose and configuration files provided in the [LOVE-integration-tools](https://github.com/lsst-ts/LOVE-integration-tools) repo. Please follow the instructions there.
+
+## Initialize Environment variables
+In order to use the LOVE-manager, some environment variables must be defined before it is run.
+All these variables are initialized with default variables defined in :code:`.env` files defined in the corresponding deployment environment defined in [LOVE-integration-tools](https://github.com/lsst-ts/LOVE-integration-tools). The are:
+
+* `ADMIN_USER_PASS`: password for the default `admin` user, which has every permission.
+* `USER_USER_PASS`: password for the default `user` user, which has readonly permissions and cannot execute commands.
+* `CMD_USER_PASS`: password for the default `cmd` user, which has readonly permissions but can execute commands.
+* `LOVE_MANAGER_REDIS_HOST`: the location of the redis host that implements the `Channels Layer`.
+* `REDIS_PASS`: the password that the LOVE-manager needs tio use to connect with `redis`.
+* `PROCESS_CONNECTION_PASS`: the password that the LOVE-producer will use to establish a websocket connection with the LOVE-manager.
+* `AUTH_LDAP_SERVER_URI`: (deprecated) the location of the LDAP authentication server. No LDAP server is used if this variable is empty
+
+# Local load for development
+We provide a docker image and a docker-compose file in order to load the LOVE-manager locally for development purposes, i.e. run tests and build documentation.
+
+This docker-compose does not copy the code into the image, but instead it mounts the repository inside the image, this way you can edit the code from outside the docker container with no need to rebuild or restart.
+
+## Load and get into the docker image
+Follow these instructions to run the application in a docker container and get into it:
+
+```
+docker-compose up -d
+docker-exec manager bash
+```
+
+## Run tests
+Once inside the container you will be in the `/usr/src/love/manager` folder, where you can run the tests as follows:
+```
+pytest
+```
+
+## Build documentation
+Once inside the container you will be in the `/usr/src/love/manager` folder, where you can move out to the `docsrc` folder and build the documentation as follows:
+```
+cd ../docsrc
+./create_docs.sh
+```

docker-compose.yml

@@ -0,0 +1,15 @@
+version: "3.7"
+
+services:
+
+  manager:
+    container_name: manager-local
+    build:
+      context: .
+      dockerfile: Dockerfile-dev
+    image: love-manager-image-mount
+    volumes:
+      - .:/usr/src/love
+    command: ""
+    stdin_open: true
+    tty: true

docs/html/_sources/index.rst.txt

@@ -9,11 +9,12 @@ Welcome to LOVE-manager's documentation!
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
+   :numbered:
 
-   modules/introduction.rst
-   modules/authentication.rst
-   modules/connection.rst
-   modules/subscriptions.rst
+   modules/overview.rst
+   modules/how_to_use_it.rst
+   modules/how_it_works.rst
+   modules/readme_link.rst
    apidoc/modules.rst
 
 

docs/html/_sources/modules/how_it_works.rst.txt

@@ -0,0 +1,55 @@
+============
+How it works
+============
+
+.. image:: ../assets/Manager_Details.svg
+
+
+LOVE-manager parts
+==================
+The LOVE-manager is composed by different software components, as explained below.
+
+API
+---
+Provides a REST API with endpoints to request and validate access tokens.
+When a client (LOVE-frontend) tries to login it sends the users credentials (user and password) through an HTTP request to the API, which responds with the token (if the credentials are valid) or an error (if the credentials are invalid). The validation is done comparing searching the given user in the :code:`DB` and comparing the given password.
+
+Consumers
+---------
+Once the client (LOVE-frontend) has an access token, it can establish a websocket connection with LOVE-manager's :code:`Channels Layer`. Each client (LOVE-frontend) instance is connected to a unique :code:`Consumer` instance, which handles the communication with that particular client.
+Similarly, a :code:`Consumer` also handle the communication with a LOVE-producer instance.
+
+Each :code:`consumer` communicates only with their corresponding clients. In order to receive messages from other clients, the consumer of a client must subscribe to a given group.
+When a client sends a message to a group, it is forwarded to all the consumers subscribed to that group, which in turn send the message to their corresponding clients. All the message routing is done in the :code:`Channels Layer`.
+
+Channel Layer
+-------------
+The :code:`Channels Layer` acts as the message handler, and is in charge of making sure every consumer receives the messages from the groups it has subscribed to.
+When a client sends a message to its :code:`Consumer`, it is forwarded to the :code:`Channels Layer`. The :code:`Channels Layer` forwards the message to all the consumers subscribed to the group, and each consumer forwards the messages to its corresponding client.
+
+DB
+--
+The :code:`DB` is used to model and store the users data (username, password and permissions). It is currently implemented in a simple :code:`.sqlite3` file, and is initialized with default users and groups.
+
+
+Example
+=======
+In the figure above, we can see that :code:`Frontend 1` subscribes to telemetry :code:`tel1` while :code:`Frontend 2` subscribes to telemetries :code:`tel1` and :code:`tel2`.
+When :code:`Producer` sends a value for :code:`tel1` to its consumer :code:`Consumer producer`, the latter forwards :code:`tel1` to the :code:`Channels Layer`, which forwards :code:`tel1` to :code:`Consumer 1` and :code:`Consumer 2`, each of which send :code:`tel1` to  :code:`Frontend 1` and :code:`Frontend 2` respectively.
+
+Then, when :code:`Producer` sends a value for :code:`tel2` to :code:`Consumer producer`, the latter forwards :code:`tel2` to the :code:`Channels Layer`, which forwards :code:`tel2` to :code:`Consumer 2` only. Then :code:`Consumer 2` forwards the message to :code:`Frontend 2`.
+In this case :code:`Frontend 1` (and :code:`Consumer 1`) never received :code:`tel2` because its not part of :code:`Consumer 1` subscriptions.
+
+
+Code organization
+==================
+
+Currently the application is divided in the following modules and files:
+
+* :code:`api`: This module contains the :code:`API` Django app, which defines the models and API endpoints for authentication. For more details please refer to the ApiDoc section
+* :code:`subscription`: This module contains the Django app that defines the consumers that handle the websocket communication.
+* :code:`manager`: This module contains basic Django configuration files, such as urls and channels routing, etc.
+* :code:`manage.py`: This module is the main executable of the Django application, used mostly for development purposes, but also to execute some actions over the database, such as applying migrations, creating data, etc.
+* :code:`pytest.ini`: This is the configuration file for the Pytest testing module.
+* :code:`requierements.txt`: This file defines the python libraries required by the application.
+* :code:`runserver.sh` and :code:`runserver-dev.sh`: These are simple scripts used to run the application inside the docker images.