You can use JASS locally either using the command line interface in a terminal, or by running a web server. Deployment in a public server is also later discussed in this document.
You can use JASS locally either using the command line interface in a terminal, or by running a web server.
Deployment in a public server is also later discussed in this document.
Basic installation
------------------
You need **python3** to install and use JASS. As of April 2021, JASS runs on python 3.x with x < 9.
You need **python3** to install and use JASS. As of July 2021, JASS runs on python 3.x with x < 9 on Windows and Linux platforms.
JASS runs on python 3.9 only on Linux platforms
.. warning::
The Installation of JASS crashes for python 3.9 on Windows and on Linux : various packages (including tables) are not compatible with python 3.9. Moreover celery is also not compatible with python 3.9 .
The Installation of JASS crashes for python 3.9 on Windows : various packages (including tables) are not compatible with python 3.9.
Moreover celery is also not compatible with python 3.9 .
Installation for a user-only profile
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
JASS can be installed like any other python package, for instance with pip:
Installing it this way will automatically import and setup all of the dependencies required to run JASS.
This is pretty much all you need to do to use JASS on the command line, or to run a local personal web server.
Installation for development purpose
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A procedure for the correct installation of JASS in Anaconda environment for development purpose is developed in detail below.
...
...
@@ -48,10 +66,18 @@ In a TERMINAL window, type the following instructions:
**5. Installing JASS dependencies**
On Linux computer:
.. code-block:: shell
pip install -r requirements.txt
On Windows computer:
.. code-block:: shell
pip install -r requirements_Windows.txt
**6. Installing JASS for development purpose**
.. code-block:: shell
...
...
@@ -66,7 +92,8 @@ In a TERMINAL window, type the following instructions:
Installing it this way will automatically import and setup all of the dependencies required to run JASS.
This is pretty much all you need to do to use JASS on the command line, or to run a local personal web server. To deploy JASS on a public web server, please refer to the "Public server deployment" section.
This is pretty much all you need to do to use JASS on the command line, or to run a local personal web server.
To deploy JASS on a public web server, please refer to the "Public server deployment" section.
Additional software installation on Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
...
...
@@ -99,11 +126,13 @@ Then, you can install RabbitMQ with the "choco install" command:
Run JASS as a web application (optional)
----------------------------------------
To run locally JASS as a web application, you need to launch two servers in two different processes, the `celery` task management server and the web server. The web server handles the HTTP requests, and sends all computation requests to the task management server.
To run locally JASS as a web application, you need to launch two servers in two different processes, the `celery` task management server and the web server.
The web server handles the HTTP requests, and sends all computation requests to the task management server.
launching the two servers on Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The command lines below show how to launch the two servers. Please note that you should of course not use this for any use beyond tests and personnal use, we provide further instructions below to deploy JASS on shared/public servers.
The command lines below show how to launch the two servers. Please note that you should of course not use this for any use beyond tests and personnal use,
we provide further instructions below to deploy JASS on shared/public servers.
.. code-block:: shell
...
...
@@ -113,7 +142,8 @@ The command lines below show how to launch the two servers. Please note that you
# launch the web server
jass serve
By default, the Jass server will listen to requests on the port 8080 of your machine. You can control the host and port that the JASS standalone webserver listens to through two environment variables, ``JASS_HOST`` and ``JASS_PORT``, that you just have to set before to launch the web server.
By default, the Jass server will listen to requests on the port 8080 of your machine. You can control the host and port that the JASS standalone webserver
listens to through two environment variables, ``JASS_HOST`` and ``JASS_PORT``, that you just have to set before to launch the web server.
Launching the celery server on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
...
...
@@ -127,6 +157,8 @@ In order to launch the celery server on windows, it is necessary to use the foll
.. warning::
The command recommended for Linux crashes when it is used on windows due to incorrect recognition of the prefork option on windows by the billiard library.
The part “--pool=solo” is necessary on windows because this is the only option of celery that works on windows.
In addition, on a Windows computer, you must use the version 5.0.5 of celery. This constraint is specified in the file: requirements_Windows.txt
Launching the web server on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
...
...
@@ -137,9 +169,50 @@ The web server is launched in another terminal (the same as on Linux):
jass serve
Installing JASS with docker
---------------------------
Using docker has several advantages: we no longer have to worry about the versions of celery and rabbitMQ as well as the launch of the JASS servers.
The first step is installing docker on your computer as an administrator.
On Windows, you can use chocolatey to install docker-desktop (to install chocolatey, please refer to the section **Additional software installation on Windows**).
Then, you must open a powershell in **administrator mode** and run the following command:
.. code-block:: shell
choco install docker-desktop
For docker-desktop to work on Windows, you will also need to install a Linux distribution for Windows. To do this, follow the instructions on the page:
https://docs.microsoft.com/en-us/windows/wsl/install-win10 (Windows Subsystem for Linux Installation Guide for Windows 10).
Finally, you must restart your computer for the changes made to take effect.
After installing docker and loading the code of JASS from PASTEUR's Gitlab (see the section **Basic installation of JASS**), you must launch a powershell window.
Then, you change directory to go to the root folder of JASS and run the following command to create the docker images necessary for the operation of JASS:
.. code-block:: shell
docker-compose up --build
You should also place the initTable.hdf5 file in the folder data of JASS.
You will be able to access the web interface of JASS using the request: http://localhost:8080.
To quit JASS, you must type **CTRL + C** in the powershell.
If there is no code change, it is not necessary to recreate the docker images.
You can launch a powershell window, go to the root directory of JASS and run the command:
.. code-block:: shell
docker-compose up
Public server deployment (optional)
-----------------------------------
Ansible playbooks are available in the `ansible folder of the source repository <https://gitlab.pasteur.fr/statistical-genetics/jass/tree/master/ansible>`_. These playbooks automate the initial configuration of the system (for a server using CentOS), and the initial installation or the update of the code from the repository.
Ansible playbooks are available in the `ansible folder of the source repository <https://gitlab.pasteur.fr/statistical-genetics/jass/tree/master/ansible>`_.
These playbooks automate the initial configuration of the system (for a server using CentOS), and the initial installation or the update of the code from the repository.
In this specific deployment, the JASS web application is hosted by an NGINX server, connected through the uWSGI library. It communicates with a celery service that handles the user-launched tasks. Many other deployment options are of course possible, use whichever suits your infrastructure!
In this specific deployment, the JASS web application is hosted by an NGINX server, connected through the uWSGI library.
It communicates with a celery service that handles the user-launched tasks. Many other deployment options are of course possible, use whichever suits your infrastructure!
