Installation

Building and running the backend

Prerequisites

1. Setup Java JDK

Running Gradle always requires a Java JDK version 8 or higher. For this project it is recommended to use version 11 of the Java JDK. First download the installer for the Java JDK.

Windows

Make sure you select the appropriate operating system, architecture and version 11 of the JDK. Download and run the .msi file. Make sure the "Configure JAVA_HOME variable" option is checked. This option is disabled by default in the installer.

After the installation has finished, open CMD and check with java -version if the installation was successful.

2. Setup Gradle

Gradle is a build tool used to build the backend. Gradle version 7.1 is required for the backend. A list of the different versions can be found here. If you do not install Gradle via a package manager, there is a detailed description of how to install Gradle manually.

After the installation has finished, open CMD and check with gradle -v if the installation was successful.

3. Set up database management systems

MongoDB

The database management system Mongodb is used for the persistence of the reports to be saved. Download the latest version of MongoDB and install it. It is recommended to install MongoDBCompass with MongoDB Shell as well.

PostgreSQL

The database management system PostgreSQL is used for the persistence of user account data. Download and install the latest version of PostgreSQL.

The PostgreSQL database must be created by yourself and is not automatically generated by the project. To do this, create a PostgreSQL user with a secure password and remember the user credentials. To create a database in PostgreSQL, the latest version of pgAdmin is recommended.

4. Get the Project

You can download the project as a ZIP file or clone it with:

   git clone https://github.com/informatik-heilbronn/transparenz-cockpit

If you downloaded the zip file, extract the project to a path of your choosing.

Build

Make sure you have met the prerequisites for the backend. Open CMD, navigate to the project folder and run the following command:

   gradle backend:build

Run

Before you can run the backend, you need to create and configure the databases. Unlike the PostgreSQL database, the MongoDB database is created automatically. Accordingly, you have to create the PostgreSQL database yourself.

In the backend folder is the transparentcockpit.config.sample file, which provides a template for specifying the configuration. Enter your database information in this file using an editor. Rename the file and remove the .sample so that the file is called transparentcockpit.config afterwards.

Note: If you have not created a user for the MongoDB database, you can create a new admin user with the following commands in Mongo shell:

   use admin
   db.createUser({ user: "<user>" , pwd: "<password>", roles: ["userAdminAnyDatabase", "dbAdminAnyDatabase", "readWriteAnyDatabase"]})

After you have done all the preparations, open CMD, navigate to the project folder and run the following command:

   gradle backend:run

Build and Run the Frontend

##Prerequisites In order to compile all code and setup all dependencies required to render the website data, a few installation steps are necessary. First, if not already installed, you will need to install the following components on your local OS:

• Node.js
• NPM

Node.js allows you to compile and run a JavaScript project. Necessary, as nearly all parts that make up the frontend are written in JavaScript. NPM on the other hand (which stands Node Package Manager) is an environment that provides, among other applications, tools to run, build and test JavaScript components. For this reason it is used in combination with Node.

Installation for Windows

Node.js can be downloaded from the browser. Following this link https://nodejs.org/en/download/ download the latest version of Node.js. Follow the description on the website and of the installer during the installation. The NPM is included as well. After accepting terms and conditions and finishing the installation, check wether Node has been installed properly by checking its version in the command line:

node -v

Installation for Ubuntu

For Ubuntu systems there are different ways to perform the installation. Here the most direct way through the terminal will be shown. Open the terminal and type the following:

sudo apt update
sudo apt install nodejs npm

Just like for Windows, verify that the package has been installed by checking the version with

nodejs --version

This should output the version number of the currently installed node version. If any problems should occur during the process, refer to this website https://linuxize.com/post/how-to-install-node-js-on-ubuntu-20-04/. Here alternative methods are also presented to install Node.js and NPM.

Clone Project

After this, the next step is to clone this project in order to have all necessary code and resources for building the frontend locally. Just like for the backend setup, you can either download the project's .zip or clone it via the

   git clone https://github.com/informatik-heilbronn/transparenz-cockpit

command.

Build and Run

Next you'll have to open the command line again. For Windows open either git or Powershell. For Ubuntu the normal terminal will do. Head into the directory of the cloned project with

cd <project directory>

Now do the first project build with

gradle frontend:build

This will attempt to build the fronted directory, which should be contained directly within the project's root directory. There might occur some errors referring to missing gradle dependencies or missing configurations. In this this case refer to the backend build documentation, which describes how to set up gradle. A possible source for such errors lies within the configuration of the JVM for which gradle is configured to build. Here you must set the "Amazon Corretto Java 11" version as the selected JDK. In case you are working form within an IDE, this config can usually be found under Settings and then Settings for build tools (in this case gradle). If the JDK isn't installed on your system yet, do this first before proceeding (this is also described in the "JDK" section of the backend build documentation). Other JDKs may also work, but since these versions weren't used during testing, these instructions should not be reliably applied to them.

Next, since this will be the first time running the project, you won't be able to run it right away, as some additional components, such as graphics, need to be installed through NPM, without which the run will fail. To do this, from the current directory navigate now to the frontend directory with

cd ./frontend

Then do

npm install

which installs the missing resources. This step may take a while. After this do

npm ci

which installs even more dependencies specified in the package-lock.json, also present in the directory.

Finally after having successfully executed the above steps, you may now run the frontend with

npm run dev

This will compile the source code and start rendering the website, which by default will be hosted locally on your machine for now.