CART User Manual ‐ Build options

Build options

Build options for the tool are all recorded in the build_parameters.yml file. We will first provide instructions on how to edit that file and then explain it in more detail.

Editing the Build Parameters File

Why the build parameters file is so important and useful:
The tool is a combination of many different software packages and libraries. As such it is complicated to install the tool in any given environment (your local laptop for instance) - to overcome this challenge we use Docker, a software container system that makes installing the tool easy. We then install docker and the tool on a cloud based virtual machine hosted on Amazon Web Services or any other providers.

When we “build the tool” we build a docker image that we must pass certain information to.

• The Open Street Map location and where the get the OSM pbf file that we will extract the road network from
• The types of vehicles we would like to enable in the tool environment (note we do not enable all vehicles types because there is a major time cost every time you update the tool )

We save this information in the build_parameters.yml file.

When we run the tool we also pass some information to the Docker environment - we pass many more arguments when we run the tool to prevent “rebuilding” the tool. Rebuilding the tool can take up to an hour so we don’t want to rebuild if we are just changing the cloud environment we are using (AWS or gdrive) or updating a file id (if using gdrive).

Changing the integration
In build_parameters.yml, leave storage_context blank if using local data or the server API, or
storage-context: gdrive ← This one will use gdrive
storage-context: aws ← This one will use aws
Save the file and then rerun the tool. Note you do not have to rebuild the tool. If you need to change the bucketname where files are saved you can also do that here with the s3bucketname parameter.

Below is an image all of the build options - those under Build will require a rebuild, those under Run do not.
build_parameters.yml
Build:
osm-data:
Geofabrik-url: https://download.geofabrik.de/europe/monaco-latest.osm.pbf
vehicle-types:
- wheelbarrow
- 3wheeler

Run:
storage-context: gdrive
aws:
accesskeyid: ***************
secretkey: ****************
s3bucketname: tool-dev
gdrive:
credentials_file: gdrive_creds.json
customer_data_id: *******
facility_data_id: ****************
root_folder_id: ******************

Note:

• Credentials_file: is a file that allows programmatic access to the gdrive from the machine. It can be obtained by following Step 1 here https://developers.google.com/drive/api/v3/quickstart/python
• Customer_data_id: is the id of the customer data - you can see the id in the URL of the googlesheets file when you view it. It should be a long string of numbers and letters between forward slashes.
• Facility_data_id: this is the extra_points file
• Root_folder_id: this is the id for the folder where you will save your output data. That folder should have a folder inside it called output.

Building the Tool

Clean build of the tool

Let's describe how to do a “clean build” where everything gets rebuilt. This is what DataKind does when it makes changes to the code base and then rebuilds the tool.

1. [Optional] First make any updates to the build_parameters.yml file (See above for instructions)
2. Now run the build script by typing: sh s_build_docker.sh, this will rebuild all parts of the tool - it may take over an hour to complete.
3. Once complete you will have a terminal screen where you can type commands again and the various items printing out will have stopped.

Updating the OSM Data

If you have updated the OSM data and verified that the Geofabrik website has also been updated you can update just the OSM data for the tool.

Follow steps 1-2 above, and then run sh s_update_osm_data.sh, this will still take 30-45 min most likely but will be a bit shorter than the initial build.