windows-installation-guide.md

Windows Installation Guide

Table of Contents

• Installing Java
• Installing Gradle
• Installing Postgresql and Postgis
• Installing Git
• Clone Tombolo Digital Connector Repository

Installing Java

Check if java is already installed

• Click on the Start Button and type 'Command Prompt' and hit enter

• In the window type 'java -version'

• If your output looks like the one in the screenshot below, then probably java is not installed on your computer.

• It could be a possibility that java is installed but Environment Variable is not set.

• To check that go to 'C:\Program Files' and see if you see a folder named Java. If there is no folder like that then we can be sure that Java is not installed on your computer.

• In case you find the Java folder there, then skip to Set Environment Variable Section

Install Java

Check for OS Architecture

• Before we start downloading Java, we need to check the what is your OS Architecture in order to install the correct version of Java
• There are two ways to do it:
  • Through File Explorer
    • Click on Start -> File Explorer, if that option is not available, open any folder
    • Right Click on 'This PC' and choose Properties as shown in the screenshot below
    • Once done look for the 'System Type' on a window similar to the one below
    • If your system type is '64 bit operating system' then your system has 64 bit architecture
  • Through Command Prompt
    • Click on the start button and type ‘command prompt’, click on the application to open. Once your command prompt is open type either of the following commands in order to get the architecture of the system
      • wmic os get osarchitecture
        
      • echo %PROCESSOR_ARCHITECTURE%
        

Download and Install Java

• Once you know the architecture information of your system, go here
• Accept the License and choose the version of JDK that suits the version of your operating system, e.g. if your system is 32 bit choose 'Windows x86', if it is 64 bit choose 'Windows x64'
• In my case it happens to be 64 bit architecture, thus we are downloading ‘Windows x64’ version.
• Once downloaded, double click on the downloaded file, based on your security setting you might get a dialog to confirm opening of the .exe file, just click Run. Now you should see a dialog like this
• Click Next. On the next screen make note of the installation directory, in my case it is installing in C:\Program Files\Java\jdk1.8.0_151\ which you can see at the bottom left side of the screen. This is required to set the environment variable at a later stage
  
• Click Next. The installation will begin, while installing it may ask you to change the installation directory for JRE, just let it set to default and click Next.
  
• Click Finish on the next screen, once the installation is completed.

Check Installation

• Go to the command prompt and type 'java -version'
• If you see something like above then Environment Variable is not set.

Set Environment Variable

• Open File explorer -> Right click on 'This PC' -> Click on Properties, Once you do that you will get a window like this
  
• Click on Advanced System Settings. You should get a Window like this
• Click on Environment Variables, which should give you a window like this
• Click on Path and Click Edit. In Variable value at the end type the path of the Java installation directory, for which you made the note earlier which in my case is C:\Program Files\Java\jdk1.8.0_151\ and append bin at the end like this.
  
• Click OK and open a new Command Prompt window (as explained earlier) and type java -version. Now you should see something like this.
  

Congratulations you have successfully installed java, now let's move on to installing Gradle

Installing Gradle

Check if gradle is installed

• Open Command Prompt and type gradle --version. If your output looks like this
• Then the gradle application is not installed.

Download and Install Gradle

• In order to install gradle go here and scroll down for the latest version and click on complete as shown here
• Save the file and unzip it at your preferred location, in my case it is unzipped under Program Files in order to be consistent as application are usually installed under Program Files.
• Once unzipped navigate to the bin folder of gradle which in my case is C:\Program Files\gradle-4.3.1-all\gradle-4.3.1\bin as the files were extracted in Program Files as described earlier. Copy the path of the bin folder by clicking the Address Bar in the File Explorer as shown in the screenshot below.
• Once the path is copied, follow the steps described in the Java Installation section to navigate to the Environment Variable windows, as shown below
• Choose Path and click Edit, you would see a window like this
• Click on New and Paste the path that you copied of Gradle bin, Now your window should look like this
• Click OK to save and dismiss this dialog box. Click OK again to dismiss the Environment Variable dialog box and Click OK to dismiss System Settings dialog. Now open a new window of Command Prompt and type gradle --version and you should see something like this

Congratulations now you have gradle installed on your computer. Let’s move to install Postgresql

Installing Postgresql and Postgis

Install Postgresql

• To install Postgresql, go here. You should see a screen something like
  
• Choose the latest version and Select the operating system, based on the architecture of the system you need to choose the Operating system. In my case the system architecture is 64 bit, below screenshot displays the version and operating system selected
  
• Once the options are selected, click Download Now. Once the file is downloaded double click to open it and click Run. The system will start doing some processing and after a second or two would give you Set up dialog. Click Next
• It will ask you to choose the installation directory. Leave it to default and click Next, Click Next and Select Components screen but make sure all the options are by default checked, if they are not checked, check them and click Next
  
• On next screen, the setup process would ask to setup the data directory, leave it to default and click Next.
• On the next screen the installation process would prompt you to create superuser password, type in the password and make a note of it, it will be required at a later stage.
  

Note: The user account that postgresql creates is not called superuser it is called postgres but the account will have full access to the database.

• On the next screen, it will ask you to set the port number, leave it to default and click Next
  
• On the next screen choose the locale, in my case it is English, United Kingdom as shown below. Once locale is chosen, click Next
  
• On the next screen, the process will show all the choices you have made in the installation process as shown below, Click Next and Click Next again
  
• The system will start installing postgresql, which could take a sometime. Once installed you should get a screen like below, make sure Stack Builder option is checked as we still need to download PostGis and other JDBC and ODBC drivers. Click Finish
  

Selecting Drivers and Spatial Extensions

• Stack builder installation dialog will pop up, choose the Postgresql version you just downloaded in the drop down box, Click Next
• On below screen, expand database drivers and choose, pgJDBC and psqlODBC as shown in the screenshot below. (make sure for psqlODBC you choose the right architecture). Also expand the Spatial Extensions section and choose PostGIS option. Click Next
• Leave the download directory as default and click Next and click Next again

JDBC Installation

• Click Next on the below screen and JDBC installation will begin

• Once the installation is done you would see a screen like this, but the installation is only completed for one driver, we still have got 2 more drivers to install as we have selected 3 drivers on Stack Builder. Click Finish

ODBC Installation

• Once you are done with the JDBC setup, next setup will start which is ODBC, click Next
• Leave the default installation directory and click Next and Click Next again and installation will begin
• Once the installation is done, click Finish.

Postgis Installation

• Now the third installation will start which is PostGis, accept the terms and conditions by clicking I Agree
  
• Click Next on Choose Components screen and make sure PostGIS is selected.
• Leave the installation directory to default on Choose Install Location screen and Click Next
• Click Yes on all the below shown dialogs
  
• Click Close when the installation is finished
• Click Finish on Stack Builder Installation Completed screen

Note: We still have to set the Environment Variable path, as psql command will still not work on Command Prompt

Set Environment Variable

• Navigate to the bin directory of postgresql installation, which in my case is C:\Program Files\PostgreSQL\10\bin. Click on the address bar of the file explorer window and copy the path.
• Navigate to the Environment variable window as described in the Java installation section, and when you are on Edit environment variable screen, click on New and paste the address of the Postgresql bin directory that you copied a little while ago and click OK
  
• Now open a new window of Command Prompt and type psql -U postgres as by default Postgresql creates a postgres account, upon entering the above command it will prompt you to enter password for postgres user which you have set while installing the Postgresql. Type the same password in and you should see something like below. Screenshot below shows a Postgresql shell. Type \q to quit.
  

Congratulations now you have installed Postgres and Postgis.

Installing Git

Check if Git is already installed

• Lets first check if Git is installed on your machine or not. Open a new Command prompt window and type git --version, if you see something like below then we could say that git is not installed on your computer. It could be that Git is installed but Environment Variable is not set. You could check that by going to the C:\Program Files if you would see a folder named Git then you just need to set Environment Variable path. If that is the case please feel free to the section where we are setting Environment Variable
  

Download Git

• Go here and scroll down to Downloads section and click the latest version of the application which has .exe extension, which in my case is Git-2.15.0-32-bit.exe
  

Install Git

• Double click on the file once it is downloaded and click Run.
• Click Next on the license page
• Leave the installation directory to default on Select Destination Location box and click Next
• Click Next on Select Components box
• Click Next on Select Start Menu Folder box
• Click Next on Adjust your PATH environment box
• Click Next on Choosing HTTPS transport backend box
• Click Next on Configuring the line ending conversions box
• Click Next on Configuring the terminal emulator to use with Git Bash box
• Click Install on Configuring extra options, this will start installing Git on your machine
• Once the installation is complete, click Finish

Note: We still need to set environment variable in order for git command to work from Command Prompt

Set Environment Variable

• Navigate to the bin directory of Git which in my case is C:\Program Files\Git\bin. Click on the address bar of the file explorer and copy the path.
  
• Navigate to the Environment variable window as described in the Java installation section, and when you are on Edit environment variable screen, click on New and paste the address of the Git bin directory path that you copied a little while ago and click OK
  
• To test the installation again, open a new Command Prompt and type git --version and you should see something like this.
  

Congratulations, you now have git installed on your machine.

Now that we have all the dependencies installed, let’s start working with Tombolo

Clone Tombolo Digital Connector Repository

• To clone Tombolo Digital Connector repository, click here then click on Clone or Download and copy the path
• Open a new Command Prompt and make sure that you present working directory is your home directory. You can check that by looking the path in the Command Prompt window before >, in my case is looks like this
• If yours also follows the same pattern as C:\Users\<user-name> then you are good to go. If not then change it by typing cd C:\Users\<user-name>. Now that we are in our home directory, we can type following commands to clone TomboloDigitalConnector repo.

cd Desktop
mkdir Tombolo
cd Tombolo
git clone https://github.com/FutureCitiesCatapult/TomboloDigitalConnector.git

• Now wait for it to download, when it is downloaded you would see something like below.
• Now type cd TomboloDigitalConnector.
• We have rename 2 project files gradle.properties.example and apikeys.properties.example. To do that just type the following commands in Command Prompt

copy gradle.properties.example gradle.properties
copy apikeys.properties.example apikeys.properties

Setup Databases

Main Database

• Type the following commands

psql -U postgres
Enter the password for the account and hit enter (You have set this password while installing postgres)
CREATE USER tombolo WITH PASSWORD ‘tombolo’;
CREATE DATABASE tombolo WITH ENCODING=UTF8;

• Make tombolo a superuser

ALTER USER tombolo WITH SUPERUSER;

• Type \q to quit
• We now need to create postgis extension

psql -d tombolo -U tombolo
Enter the password as tombolo and now Type the following commands
CREATE EXTENSION postgis;
SET NAMES ‘UTF8’;

• Type \q to quit
• Now run the sql script to setup your database

psql -d tombolo -U tombolo < src\main\resources\sql\create_database.sql
Enter the password as ‘tombolo’

Test Database

IMPORTANT NOTE: This database is not optional, if not set up the tests will fail.

• The steps for setting up the test database are the same as for the main database. Thus follow the steps as in the Main Database section and replace tombolo with tombolo_test everywhere even for the passwords as follows.

psql -U postgres
# Enter the password for the account and hit enter
# (You have set this password while installing postgres)
CREATE USER tombolo_test WITH PASSWORD ‘tombolo_test’;
CREATE DATABASE tombolo_test WITH ENCODING=UTF8;
ALTER USER tombolo_test WITH SUPERUSER;

\q # to quit

psql -d tombolo_test -U tombolo_test
Enter the password as tombolo and now Type the following commands
CREATE EXTENSION postgis;
SET NAMES ‘UTF8’;

\q # to quit

psql -d tombolo_test -U tombolo_test < src\main\resources\sql\create_database.sql
Enter the password as ‘tombolo_test’

Below are just the screenshots for the steps:

Congratulations now your both the databases are setup.

Build and Run the project

Build

• Now you are all set to build the project TomboloDigitalConnector. To build the project in Command Prompt type the following

gradle clean build

• Running the aforementioned command should start downloading the packages required to run DigitalConnector, once the packages is downloaded it will start building the DigitalConnector and start running the tests, on a machine with 8gb of ram it should not take more than 15 minutes to run the tests, once the downloads are done.
• Below are couple screenshots of the start of the process and end of the process.

Congratulations you have successfully built the Digital Connector. Now let’s try to run an example.

Run

• Type the following command in the Command Prompt

gradle runExport -Precipe=src\main\resources\executions\examples\reaggregate-traffic-count-to-la.json -Poutput=reaggregate-traffic-count-to-la_output.json

• Below are couple of screenshots of start and end of the process.

View output in a file

start notepad reaggregate-traffic-count-to-la_output.json

View output in a Folder

start .