doc: update RAEDME of dspot-web mojo (STAMP-project#941)

README-developers.md

@@ -53,7 +53,7 @@ We accept contribution in form of pull requests. Pull requests must include at l
 
 For each pull request opened, travis is triggered. Our CI contains different jobs that must all pass.
 
-There are jobs that execute the test for the different module of DSpot: `DSpot Core`, `DSpot Maven plugin`, `DSpot diff test selection`, and `DSpot prettifier`. 
+There are jobs that execute the test for the different module of DSpot: `DSpot Core`, `DSpot Maven plugin`, `DSpot diff test selection`, and `DSpot prettifier`.
 
 There are also jobs for different kind of execution: from command line, using the maven plugin from command line and from a configuration in the pom, on large and complex code base.
 
@@ -103,6 +103,27 @@ dspot.amplifyTest(String fulQualifiedName, List<String> testCasesName); // will
 dspot.amplifyAllTests(); // will amplify all test in the test suite.
 ```
 
+## Using DSpot-web
+
+## Directories
+
+Projects being analysed by the DSpot Web UI are cloned and analysed in a dedicated directory, which can be configured in section `work_dir` of the main configuration file of the application: `d_spot_web.conf`.
+
+In this directory each directory is a project, with all required files and information for the project stored inside. A typical architecture looks as follows:
+
+* `work_dir`
+  - `project_a`
+    - `src` is the git extract (clone) of the repository.
+    - `output` is the hierarchy generated during the dspot execution.
+    - `results.zip` is the compressed file of the results.
+    - `logs` contains the logs of all major actions:
+      - `dspot.log` is the log of the dspot execution.
+      - `git_clone.log` is the log of the `git clone` command.
+      - `git_pull.log` is the log of the last `git pull` command, if relevant.
+
+Please refer to [the dedicated README](dspot-web/v2/README.md) for information about how to install, configure, start and stop the application.
+
+
 ## Contributing
 
 DSpot is licensed under LGPLv3. Contributors and pull requests are welcome.

dspot-web/v2-mojo/README.md

@@ -19,9 +19,9 @@ $ cpanm Mojo::Pg
 $ cpanm Archive::Zip File::Copy::Recursive DateTime
 ```
 
-### Initialising the application
+### Initialising the database
 
-Setup a PostgreSQL DB for Minion:
+Setup a PostgreSQL DB for Minion, the job management framework:
 
 ```
 postgres=# CREATE USER dspot_minion WITH PASSWORD 'pass4minion';
@@ -30,11 +30,97 @@ postgres=# CREATE DATABASE dspot_minion OWNER dspot_minion;
 CREATE DATABASE
 ```
 
+## Configuration
+
+Configuration is done in file `d_spot_web.conf`:
+
+```
+{
+  'secrets' => ['abc7qzverq3rcqevq0d178qzabvftq96evfab563'],
+
+  # See README.md for Posgres configuration. Only used for job management.
+  'conf_pg_minion' => 'postgresql://dspot_pg_user:dspot_pg_password@/dspot_minion',
+
+  # URL of the host (used for emails).
+  'hostname' => 'https://dspot.myhost.com',
+
+  # MAVEN_HOME.
+  'mvn_home' => '~/apache-maven-3.6.0/',
+
+  # Command to run when invoking mvn.
+  'mvn_cmd' => 'mvn clean install -DskipTests',
+
+  # Command to run when invoking dspot-maven.
+  'dspot_cmd' => 'mvn eu.stamp-project:dspot-maven:3.1.0:amplify-unit-tests -Doutput-path=../output/dspot/',
+
+  # Places where all repos will be cloned (and analysed).
+  'workspace' => '/data/dspot_workspace/',
+}
+```
+
+Parameters that can be adjusted are:
+
+ * **secrets** is a customised string used to create safe cookies.
+ * **conf_pg_minion** is the URL + credentials of the PostGreSQL cluster used by the job management component (Minion).
+ * **hostname** is used to build the instance's URL in the emails sent.
+ * **mvn_home** is the path to the maven installation that will be used for analysis.
+ * **mvn_cmd** is the pre-analysis command to use in order to build the dependency tree.
+ * **dspot_command** is the command to execute to run dspot (parameters for the mutation method are added dynamically).
+ * **workspace** is the directory where the projects will be cloned and analysed. Please remember that cloned projects can be substancially big and used disk space might increase substancially.
+
 
 ## Run the application
 
+There are two processes to start: the UI and the job management framework. 
+
+### UI
+
+Regarding the UI Mojolicious runs [hypnotoad](https://mojolicious.org/perldoc/Mojo/Server/Hypnotoad) to serve the application. It can be safely used for production-grade setups.
+
+You can run the same command again for automatic hot deployment.
+
 ```
 $ hypnotoad script/dspot_web
+* Using workspace from conf [/data/dspot_workspace/].
+* Using hostname from conf [http://ci4.castalia.camp:3000].
+* Work dir [/data/dspot_workspace/projects] exists.
+* Jobs dir [/data/dspot_workspace/jobs] exists.
+* JSON projects file [/data/dspot_workspace/projects/projects.json] exists.
+* Checking config..
+  - Using mvn home [~/Applis/apache-maven-3.6.3/].
+  - Using mvn command [MAVEN_HOME=~/Applis/apache-maven-3.6.3/ ~/Applis/apache-maven-3.6.3/bin/mvn clean install -DskipTests].
+  - Using dspot cmd [MAVEN_HOME=~/Applis/apache-maven-3.6.3/ ~/Applis/apache-maven-3.6.3/bin/mvn eu.stamp-project:dspot-maven:3.1.0:amplify-unit-tests -Doutput-path=../output/dspot].
+
+Starting hot deployment for Hypnotoad server 16493.
+```
+
+The server can be stopped using the `-s` flag:
+
+```
+$ hypnotoad -s script/dspot_web
+* Using workspace from conf [/data/dspot_workspace/].
+* Using hostname from conf [http://ci4.castalia.camp:3000].
+* Work dir [/data/dspot_workspace/projects] exists.
+* Jobs dir [/data/dspot_workspace/jobs] exists.
+* JSON projects file [/data/dspot_workspace/projects/projects.json] exists.
+* Checking config..
+  - Using mvn home [~/Applis/apache-maven-3.6.3/].
+  - Using mvn command [MAVEN_HOME=~/Applis/apache-maven-3.6.3/ ~/Applis/apache-maven-3.6.3/bin/mvn clean install -DskipTests].
+  - Using dspot cmd [MAVEN_HOME=~/Applis/apache-maven-3.6.3/ ~/Applis/apache-maven-3.6.3/bin/mvn eu.stamp-project:dspot-maven:3.1.0:amplify-unit-tests -Doutput-path=../output/dspot].
+
+Stopping Hypnotoad server 16571 gracefully.
 ```
 
-The application is served on http://localhost:3000.
+### Job management framework
+
+```
+$ cd ~/dspot/dspot-web/v2-mojo/
+$ script/dspot-web minion worker
+```
+
+To check if the worker is running is to go to the admin UI <https://dspot-demo.stamp-project.eu/admin/minion>
+
+The worker is running inside a screen on the dspot server. To see it just run screen -r to re-attach the screen (it's a foreground process so there should be lines printed on stdout).
+
+
+