Connection-Studio

This repository provides a single interface for the Connection-Lens, Abstra and PathWays projects.

Table of Contents

1. Pre-requisites
2. Environement Variables
3. Installation
4. Remote Maven Deployment

Pre-requisites

Java

• Java installed. Building has been tested with the following java version:
  • JAVA_VERSION="11.0.18"

Node JS

Install the latest version of Nodes.js, tested with node v18.12.1 and npm v8.19.2 (which is included with node).

Windows

• Download the Windows Installer (.msi)
• Open and run the .msi file, follow the the installation steps

MacOS

• Download the Mac Installer (.pkg)
• Open and run the .pkg file, follow the the installation steps

Linux

• Download the latest node version, using curln and install it :

  curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - &&\
  sudo apt-get install -y nodejs

Verify your installation

• Verifiy the node version

  node --version

• Verify the npm version

  npm --version

Maven

Install the version 3.6.3 of Maven

Windows

• Download the Maven zip archive (.zip)
• Move the archive in the location you want, and uncompress the archive using unzip:

  unzip -l apache-maven-3.6.3-bin.zip

Linux & MacOS

• Download the Maven tar archive (.tar.gz)
• Move the archive in the location you want, and uncompress the archive using tar:

  tar -xvf apache-maven-3.6.3-bin.tar.gz

Tomcat

Install the version 9.0.54 of Tomcat

Windows

• Download the Tomcat zip archive (.zip)
• Move the archive in the location you want, and uncompress the archive using unzip:

  unzip -l apache-tomcat-9.0.54-windows-x64.zip

Linux & MacOS

• Download the Tomcat tar archive (.tar.gz)

• Move the archive in the location you want, and uncompress the archive using tar:

  tar -xvf apache-tomcat-9.0.54.tar.gz

Environement Variables

Before using the application please make sure that the following variables are set in you environment :

• JAVA_HOME
• CATALINA_HOME
• Add the maven CLI to your path

tcsh or csh (MacOS)

Using the editor of your choice (we use vim),

• Open the config file of your shell :

  vim ~/.tcshrc or vim ~/.cshrc

• Then add the following lines at the end of the file :

  setenv CATALINA_HOME /the/absolute/path/to/tomcat/apache-tomcat-9.0.54
  setenv PATH $PATH\:/the/absolute/path/to/maven/apache-maven-3.6.3/bin

zsh or bash (Linux & MacOS)

• Open the config file of your shell :

  vim ~/.bashrc or vim ~/.zshrc

• Then add the following lines at the end of the file :

  export CATALINA_HOME=//the/absolute/path/to/tomcat/apache-tomcat-9.0.54
  export PATH=$PATH:/the/absolute/path/tomaven/apache-maven-3.6.3/bin

cmd (Windows)

• Type "Advanced system" in the windows search bar and click on Advanced system settings.

• On the Advanced tab, click Environment Variables

• To add Maven to your path, In the System Variables tab, scroll to find the variables PATH and click on Modify

• Then click on New and add

  /the/absolute/path/to/maven/apache-maven-3.6.3/bin

• Click on ok

• To add Tomcat to the system variables, on the System Variables tab, click on New.

• To the Variable Name field, add the following :

  CATALINA_HOME

• To the Variable Value field, add the following :

  /the/absolute/path/to/tomcat/apache-tomcat-9.0.54

• Click on Ok

Installation

• Clone the project

Web Services

• Deploy the web services war into Tomcat by running :

  Linux & MacOS

  cd connection-studio
  bash install/deploy.sh --configure

  Windows (PowerShell)

  cd connection-studio
  .\install\deploy.bat --configure

NB : The first run of scripts/deploy.sh --configure will generate a configuration file and write it to webservices/WebContent/WEB-INF/local.settings.

NB : You need to run the deploy command with --configure only once.

Front

You have two options to use the web application, you can :

1. Launch a web server using npm (it's a development server)
2. Deploy the web application into tomcat

1. Using the Development Server

• Install the node packages :

  cd connection-studio/front
  npm install

• To start the development web server, run :

  npm run start

• To access the web application, in your Web Browser go http://localhost:3000/

2. Deploying into Tomcat

• Install the node packages :

  cd connection-studio/front
  npm install

• Deploy the React war into Tomcat by running :

  Linux & MacOS

  cd connection-studio
  bash install/deploy.sh --react

  Windows (PowerShell)

  cd connection-studio
  .\install\deploy.bat --react

• To access the web application, in your Web Browser go http://localhost:8080/connectionstudio/

NB : In case of errors during the build of the react application (after a bash install/deploy.sh --react)

• Be sure to have all the required node modules :

cd connection-studio/front
npm install

• If the build is still failling, try to reinstall all node modules :

cd connection-studio/front
rm -rf node_modules/ package-lock.json
npm install

Information for Project Developers

ConnectionStudio is a front-end integrating functionalities implemented by the Pathways project. PathWays relies on Abstra, which relies on ConnectionLens (the core package; ConnectionLens also has its own front-end in the gui package, which ConnectionStudio does not need). PathWays, Abstra, and ConnectionLens are Java projects whose dependencies (on other libraries, and on each other) are handled by Maven.

The data management functionalities of ConnectionStudio are also coded in Java, as a set of servlets. Thus, for the Java part, ConnectionStudio is also a Maven-based project. As such, it declares (in the pom.xml file) a dependency on PathWays:

    <dependency>
      <groupId>fr.inria.cedar.pathways</groupId>
      <artifactId>pathways-core</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>

As usual in Maven, given that PathWays declares its dependency on Abstra, which declares its dependency on ConnectionLens, the Studio's dependency on PathWays is all we need to declare.

When changes are made on an underlying project (ConnectionLens-core, Abstra, or PathWays):

1. Re-deploy the respective project

To deploy a project:

1.1 In a repo where that project has been cloned, pull the latest changes

cd /path/to/myDependency
git pull

1.2 Then deploy it in our remote maven repository

cd core/
mvn deploy -DskipTests

1.3 Each project depending on it must be re-built and re-deployed

• If PathWays alone is modified, re-deploying PathWays suffices
• If Abstra is modified, re-deploy Abstra, then PathWays
• If ConnectionLens core is modified, re-deploy in this order: ConnectionLens-core, Abstra, then PathWays

2. Re-build ConnectionStudio's web services

Type bash install/deploy.sh to recompile ConnectionStudio's java code, generate webservices.war based on webservices/pom.xml, and deploy this war in the Web server (e.g. Tomcat)

3. Re-build and deploy ConnectionStudio's front end

Type bash install/deploy.sh --react to deploy ConnectionStudio's front end to generate connectionstudio.war baed on front/pom.xml, and deploy this war in the Web server.

How to modify the project settings

Parameters that impact the way ConnectionLens works are in the file webservices/WebContent/Web-INF/local.settings. To modify some parameters, edit this file, then rerun bash install/deploy.sh; bash install/deploy.sh --react

NB June 18, 2023: to modify parameters, I proceed as follows:

• in the ConnectionStudio repo, I modify webservices/WebContent/Web-INF/local.settings.
• then, I delete the connectionstudio and webservices folders in the Tomcat webapps folder.
• then, I redeploy the full app:
  • bash install/deploy.sh
  • bash install/deploy.sh --react
• finally, I open a new window in my browser and go to http://localhost:8080/connectionstudio