Skip to content

Latest commit

 

History

History
217 lines (152 loc) · 7.88 KB

development-guide.adoc

File metadata and controls

217 lines (152 loc) · 7.88 KB
Raw

Development guide

Project structure

The project is a multi-module Maven project.

modules.dot
Figure 1. Module dependency tree diagram

At the bottom of the module tree there are the back end and front end modules, which contain the application source code.

The standalone module is an assembly module that combines the back end and front end into a single executable JAR file.

The distribution module represents the final assembly step. It takes the standalone application and the documentation and wraps them in an archive that is easy to distribute.

Developing OptaWeb Vehicle Routing

The back end and front end are separate projects that can be built and deployed separately. In fact, they are written in completely different languages and built with different tools. Both projects have tools that provide a modern developer experience with fast turn-around between code changes and the running application.

In the next sections you will learn how to run both back end and front end projects in development mode.

Back end

The back end module contains a server-side application that uses OptaPlanner to optimize vehicle routes. Optimization is a CPU-intensive computation that must avoid any I/O operations in order to perform to its full potential. Because one of the chief objectives is to minimize the travel cost, either time or distance, we need to keep the travel cost information in RAM memory. While solving, OptaPlanner needs to know the travel cost between every pair of locations entered by the user. This information is stored in a structure called the distance matrix.

When a new location is entered, we calculate the travel cost between the new location and every other location that has been entered so far, and store the travel cost in the distance matrix. The travel cost calculation is performed by a routing engine called GraphHopper.

Finally, the back end module implements additional supporting functionality, such as:

  • persistence,

  • WebSocket connection for the front end,

  • data set loading, export, and import.

In the next sections you will learn how to configure and run the back end in development mode. To learn more about the back end code architecture, see appendix-backend-architecture.adoc.

Running the back end using the Quarkus Maven plugin

Prerequisites

  • Java 11 or higher is installed.

  • The data directory is set up.

  • An OSM file is downloaded.

You can manually set up the data directory and download the OSM file or you can use the run script to complete these tasks.

Procedure

To run the back end in development mode, enter the following command:

mvn compile quarkus:dev

Quarkus development mode

In development mode, the back end automatically restarts whenever you refresh the browser tab where the front end runs if there are any changes in the back-end source code or configuration.

Learn more about Quarkus development mode.

Running the back end from IntelliJ IDEA Ultimate

IntelliJ IDEA Ultimate has a bundled Quarkus plugin that automatically creates run configurations for modules using the Quarkus framework. Use the optaweb-vehicle-routing-backend run configuration to run the back end.

Learn more about running Quarkus applications in IntelliJ IDEA Ultimate.

Configuration

The application.properties file

The base configuration is stored in the application.properties file, under /src/main/resources/. This file is under version control. Use it to permanently store the default configuration and to define Quarkus profiles.

System properties

To override the default configuration temporarily, use system properties (-Dproperty=value).

The .env file

To override the default configuration permanently, for example to store a configuration that is specific to your development environment, use the optaweb-vehicle-routing-backend/.env file. This file is excluded from version control and so it does not exist when you clone the repository. Use optaweb-vehicle-routing-backend/.env-example to initialize your own optaweb-vehicle-routing-backend/.env file. You can make changes in the .env file without affecting the Git working tree.

See the complete list of appendix-backend-config.adoc.

See also the complete list of common application properties available in Quarkus.

Logging

OptaWeb uses the SLF4J API and Logback as the logging framework. For more information, see Quarkus - Configuring Logging.

Front end

The front end project was bootstrapped with Create React App. Create React App provides a number of scripts and dependencies that help with development and with building the application for production.

Setting up the development environment

Procedure

  1. On Fedora, run the following command to install npm:

    sudo dnf install npm

For more information about installing npm, see Downloading and installing Node.js and npm.

Install npm dependencies

Unlike Maven, the npm package manager installs dependencies in node_modules under the project directory and does that only when requested by running npm install. Whenever the dependencies listed in package.json change (for example when you pull changes to the main branch) you must run npm install before you run the development server.

Procedure

  1. Change directory to the front end module:

    cd optaweb-vehicle-routing-frontend

  2. Install dependencies:

    npm install

Running the development server

Prerequisites

  • npm is installed.

  • npm dependencies are installed.

Procedure

  1. Run the development server:

    npm start

  2. Open http://localhost:3000/ in a web browser. By default, the npm start command attempts to open this URL in your default browser.

Tip
Prevent npm start from launching your default browser

If you don’t want npm start to open a new browser tab each time you run it, export an environment variable BROWSER=none.

You can use .env.local file to make this preference permanent. To do that, enter the following command:

echo BROWSER=none >> .env.local

The browser refreshes the page whenever you make changes in the front end source code. The development server process running in the terminal picks up the changes as well and prints compilation and lint errors to the console.

Running tests

Procedure

  1. Run npm test.

Changing the back end location

Use an environment variable called REACT_APP_BACKEND_URL to change the back end URL when running npm start or npm run build. For example:

REACT_APP_BACKEND_URL=http://10.0.0.123:8081

Note that environment variables will be “baked” inside the JavaScript bundle during the npm build, so you need to know the back end location before you build and deploy the front end.

Learn more about the React environment variables in Adding Custom Environment Variables.

Building the project

Run ./mvnw install or mvn install.