Development environment

We describe how to create a developer environment to build Asqatasun locally on an Ubuntu 20.04 / Linux Mint 20 with IntelliJ Idea

Pre-requisites

  • maven
  • jdk8
  • Mysql 5.7
  • Firefox + Gecko Driver

Jdk 8

sudo apt install openjdk-8-jdk
sudo update-alternatives --config java
java -version

Maven

sudo apt install maven

Firefox + Gecko Driver

Note: it is important to stick to the specified version of Firefox

FIREFOX_VERSION="78.2.0esr"
GECKODRIVER_VERSION="v0.26.0"
FIREFOX_URL_PREFIX="https://download-installer.cdn.mozilla.net/pub/firefox/releases/"
GECKODRIVER_URL_PREFIX="https://github.com/mozilla/geckodriver/releases/download/"
FIREFOX_URL="${FIREFOX_URL_PREFIX}${FIREFOX_VERSION}/linux-x86_64/en-US/firefox-${FIREFOX_VERSION}.tar.bz2"
GECKODRIVER_URL="${GECKODRIVER_URL_PREFIX}${GECKODRIVER_VERSION}/geckodriver-${GECKODRIVER_VERSION}-linux64.tar.gz"

cd /opt
sudo wget "${FIREFOX_URL}"
sudo wget "${GECKODRIVER_URL}"
sudo tar xf "firefox-${FIREFOX_VERSION}.tar.bz2"
sudo tar xf "geckodriver-${GECKODRIVER_VERSION}-linux64.tar.gz"

Mysql

(MariaDB is not yet supported. See Allow using MariaDB with JDBC MariaDB driver)

We decide to use a Docker container

docker run \
  --name mysql \
  -e MYSQL_ROOT_PASSWORD=my-secret-pw \
  -e MYSQL_DATABASE=asqatasun \
  -p 3307:3306 \
  -d mysql:5.7

Note: in this snippet, we choose to launch Mysql on port 3307 in case another Mysql is already running on 3306

Get Asqatasun source code

git clone https://github.com/Asqatasun/Asqatasun.git
cd Asqatasun

Configure projects in IntelliJ

Open the projet in IntelliJ, it automatically discovers the Spring projets:

  • AsqatasunServer, which is the API (and nothing else)
  • AsqatasunWebappApplication, which is the whole stack engine + web application (no API included)

Default configuration values are defined:

  • server/asqatasun-server/src/main/resources/application.yml for the API server
  • web-app/asqatasun-web-app/src/main/resources/application.yml for the webapp

They can be overridden thanks to Spring Boot Externalized configuration

Within IntelliJ, they can be overridden with Run > Edit configurations

Configure, build and run: AsqatasunServer

Define here your own local configuration:

  • VM Options: -Dwebdriver.gecko.driver=/opt/geckodriver -Djdbc.url="jdbc:mysql://localhost:3307/asqatasun"

Do Run> Run AsqatasunServer. Then get directly to the Swagger interface at http://localhost:8080/ with default credentials:

  • login: admin@asqatasun.org
  • password: myAsqaPassword

Note: you must change the value of contractId from 0 to 1 or your request will end in a 500 error.

Configure, build and run: AsqatasunWebapp

Define here your own local configuration:

  • VM Options: -Dwebdriver.gecko.driver=/opt/geckodriver -Djdbc.url="jdbc:mysql://localhost:3307/asqatasun"
  • Working directory: $MODULE_WORKING_DIR$

Within IntelliJ do:

  • SHIFT SHIFT and reload all maven projects
  • Run> Run AsqatasunWebapp
  • Then browse http://localhost:8080/ and connect with credentials:
    • login: admin@asqatasun.org
    • password: myAsqaPassword

Note: if you happen to build from within IntelliJ and also from the command-line, you may end up with missing CSS and other resources in your browser. To avoid such glitches, please delete the directory asqatasun/web-app/target.

Display the Firefox launched by Asqatasun

To see the Firefox window that actually loads the audited webpage, you can add in the VM options:

-Dapp.engine.loader.selenium.headless=false

You may also pass the same option as Program arguments:

--app.engine.loader.selenium.headless=false

(Note that -D is replaced by --)