Chapter 7. Run OptaWeb Vehicle Routing locally using the runLocally.sh script

Linux users can use the runLocally.sh Bash script to run OptaWeb Vehicle Routing.

Note

The runLocally.sh script does not run on macOS. If you cannot use the runLocally.sh script, see Chapter 8, Configure and run OptaWeb Vehicle Routing manually.

The runLocally.sh script automates the following setup steps that otherwise must be carried out manually:

  • Create the data directory.
  • Download selected OpenStreetMap (OSM) files from Geofabrik.
  • Try to associate a country code with each downloaded OSM file automatically.
  • Build the project if the standalone JAR file does not exist.
  • Launch OptaWeb Vehicle Routing by taking a single region argument or by selecting the region interactively.

See the following sections for instructions about executing the runLocally.sh script:

7.1. Run the OptaWeb Vehicle Routing runLocally.sh script in quick start mode

The easiest way to get started with OptaWeb Vehicle Routing is to run the runLocally.sh script without any arguments.

Prerequisites

Procedure

  1. Enter the following command in the optaweb-vehicle-routing-distribution-7.48.0.Final-redhat-00004/sources directory. 

     ./runLocally.sh
  2. If prompted to create the .optaweb-vehicle-routing directory, enter y. You are prompted to create this directory the first time you run the script.

  3. If prompted to download an OSM file, enter y. The first time that you run the script, OptaWeb Vehicle Routing downloads the Belgium OSM file.

    The application starts after the OSM file is downloaded.

  4. To open the OptaWeb Vehicle Routing user interface, enter the following URL in a web browser: 

    http://localhost:8080
Note

The first time that you run the script, it will take a few minutes to start because the OSM file must be imported by GraphHopper and stored as a road network graph. The next time you run the runlocally.sh script, load times will be significantly faster.

Next steps

Chapter 10, Using OptaWeb Vehicle Routing

7.2. Run the OptaWeb Vehicle Routing runLocally.sh script in interactive mode

Use interactive mode to see the list of downloaded OSM files and country codes assigned to each region. You can use the interactive mode to download additional OSM files from Geofabrik without visiting the website and choosing a destination for the download.

Prerequisites

Procedure

  1. Change directory to optaweb-vehicle-routing-distribution-7.48.0.Final-redhat-00004/sources.

  2. Enter the following command to run the script in interactive mode: 

    ./runLocally.sh -i
  3. At the Your choice prompt, enter d to display the download menu. A list of previously downloaded regions appears followed by a list of regions that you can download.

  4. Optional: Select a region from the list of previously downloaded regions:

    1. Enter the number associated with a region in the list of downloaded regions.
    2. Press the Enter key.

  5. Optional: Download a region:

    1. Enter the number associated with the region that you want to download. For example, to select the map of Europe, enter 5.
    2. To download the map, enter d then press the Enter key.

    3. To download a specific region within the map, enter e then enter the number associated with the region that you want to download, and press the Enter key.

      Using large OSM files

      For the best user experience, use smaller regions such as individual European or US states. Using OSM files larger than 1 GB will require significant RAM size and take a lot of time (up to several hours) for the initial processing.

      The application starts after the OSM file is downloaded.

  6. To open the OptaWeb Vehicle Routing user interface, enter the following URL in a web browser: 

    http://localhost:8080

Next steps

Chapter 10, Using OptaWeb Vehicle Routing

7.3. Run the OptaWeb Vehicle Routing runLocally.sh script in non-interactive mode

Use OptaWeb Vehicle Routing in non-interactive mode to start OptaWeb Vehicle Routing with a single command that includes an OSM file that you downloaded previously. This is useful when you want to switch between regions quickly or when doing a demo.

Prerequisites

Procedure

  1. Change directory to optaweb-vehicle-routing-distribution-7.48.0.Final-redhat-00004/sources.

  2. Execute the following command where <OSM_FILE_NAME> is an OSM file that you downloaded previously: 

    ./runLocally.sh <OSM_FILE_NAME>

Next steps

Chapter 10, Using OptaWeb Vehicle Routing

7.4. Run the OptaWeb Vehicle Routing runLocally.sh script in air distance mode

OptaWeb Vehicle Routing can work in air distance mode that calculates travel times based on the distance between two coordinates. Use this mode in situations where you need to get OptaWeb Vehicle Routing up and running as quickly as possible and do not want to use an OSM (OpenStreetMap) file. Air distance mode is only useful if you need to smoke-test OptaWeb Vehicle Routing and you do not need accurate travel times.

Prerequisites

Procedure

  1. Change directory to optaweb-vehicle-routing-distribution-7.48.0.Final-redhat-00004/sources.

  2. Run the runLocally.sh script with the --air argument to start OptaWeb Vehicle Routing in air distance mode: 

    ./runLocally.sh --air

Next steps

Chapter 10, Using OptaWeb Vehicle Routing

7.5. Update the data directory

You can update the data directory that OptaWeb Vehicle Routing uses if you want to use a different data directory. The default data directory is $HOME/.optaweb-vehicle-routing.

Prerequisites

Procedure

  • To use a different data directory, at its absolute path to the .DATA_DIR_LAST file in the current data directory.

  • To change country codes associated with a region, edit the corresponding file in the country_codes directory, in the current data directory.

    For example, if you downloaded an OSM file for Scotland and the script fails to guess the country code, set the content of country_codes/scotland-latest to GB.

  • To remove a region, delete the corresponding OSM file from openstreetmap directory in the data directory and delete the region’s directory in the graphhopper directory.