Development Environment Setup Guide

This guide is intended to guide those who wish to contribute to the Web project in setting up a running development instance of the back-end to work with. Those seeking how to deploy this onto a production server should stay tuned. Note that this guide is still under construction!

Anyone having issues following this guide should feel free to leave a question in this this thread.

##Table of Contents:

• Windows Setup
• Linux (Ubuntu 14.04+) Setup
  • 1. Initial Setup
    • 1A. MySQL (>= 5.6)
    • 1B. PHP (>= 5.4)
    • 1C. Python
  • 2. Project Workspace
  • 3. Populating the database
  • 4. Starting the development server

Windows Setup

This section is under construction.

Linux (Ubuntu 14.04+) Setup

This setup was performed on an AWS EC2 instance running Ubuntu 14.04.

###1. Initial Setup

First, let's download the proper packages needed to run the development server.

####1A. MySQL (>= 5.6)

• Use your package manager to install mysql-server.
• Run sudo mysql_secure_installation to change some of MySQL's less secure default settings.
  • If you're running MySQL 5.7.4 or lower, run sudo mysql_install_db as well to initialize the data directory.
• Log into the MySQL console as root (mysql -u root -p) and enter your root password.
• Create the TravelMapping database:

CREATE DATABASE TravelMapping;

• The root user has too much power to be used in the public application, so let's create a more limited user:

CREATE USER '<New Username>'@'localhost' IDENTIFIED by '<New Password>';

• Grant this new user the power to read, but not modify the database:

GRANT SELECT, SHOW VIEW, PROCESS, REPLICATION CLIENT ON TravelMapping.* to '<New Username>'@'localhost' IDENTIFIED by '<New Password>';

• The database server setup is mostly complete. We'll populate it with the data later.

####1B. PHP (>= 5.4)

• Use your package manager to install php5-mysqlnd. This will install the most recent release of PHP 5.x (PHP 7.x will work as well, but the production site runs on a 5.4)

####1C. Python 3

• Make sure that Python 3 is installed. Lower versions will NOT work.

###2. Project Workspace Next, let's set up the workspace.

• Make a fork of the TravelMapping/Web repository. Then, clone your fork into a new directory TravelMapping. This is where all of the project's repositories will live.
• Next, clone the DataProcessing, UserData, and HighwayData Repositories into the same folder (you may use your own forks of these repos as well):

git clone https://github.com/TravelMapping/DataProcessing
git clone https://github.com/TravelMapping/UserData
git clone https://github.com/TravelMapping/HighwayData

• We will have to create a new configuration file to define the login credentials to our database, as well as some other parameters. So, under <PROJECT HOME>/Web/lib, create a new file tm.conf, and enter these values, each on a separate line:

<TM Database name>
<Name of TM User>
<TM User's password>
<Hostname for TM Database; use localhost unless you're using a remote DB>
<Google Maps API key> 

• Make sure this file stays private, so add a line for it in your .gitignore file: lib/tm.conf
• You will need to acquire your own Google Maps API key in order to view maps in your development instance. It is free for personal use.

###3. Populating the database *Next, we'll create the data file that we'll use to fill out our database. This script processes the LIST and WPT files into an SQL file that defines the tables in the database. While processing scripts generally depend on personal setups, this is the one I typically use:

#!/usr/bin/env bash
#
PROJ_HOME=/home/wes/HighwayMapping # Root Directory of project
HWY_DATA=$PROJ_HOME/HighwayData # Root Directory for highway data
USR_DATA=$PROJ_HOME/UserData/list_files # Root directory for user .list files

LOGS=$PROJ_HOME/Web/logs # Users' logs go here
CSV=$PROJ_HOME/csvs # Temp directory for CSV files
GRAPHS=$PROJ_HOME/graphs # Temp directory for graph files

cd $PROJ_HOME/DataProcessing/siteupdate/python-teresco

mkdir -p $LOGS $CSV $GRAPHS

echo "Pulling down new highway data..."
git -C $PROJ_HOME/HighwayData pull

echo "Pulling down new user data..."
git -C $PROJ_HOME/UserData pull

echo "Running Travel Mapping update script..."
# This is the core update script. This takes in our parameters and spits out 
# a TravelMapping.sql file in our working directory, as well as some CSV and graph files.
# 
# Graph files take a while to generate, so --skipgraphs is enabled.
$PROJ_HOME/DataProcessing/siteupdate/python-teresco/siteupdate.py --skipgraphs -w $HWY_DATA -u $USR_DATA -d TravelMapping -l $LOGS -c $CSV -g $GRAPHS

• Copy this into a .sh file and run it (make sure to make it executable). This should take several minutes.
• This produces a file TravelMapping.sql, which we can then insert into our database:

mysql -u root -p<MySQL Root Password> TravelMapping < TravelMapping.sql

• This should take another few minutes. Once this command finishes, the database will be fully populated.

###4. Starting the development server

• Now, move to the root of the Web directory and run:

php -S localhost:8080

• This will start a ad-hoc PHP server on your device. Navigate a web browser window to localhost:8080 and if all goes well, you will have an instance of the TM website to develop on your own machine. WARNING: This is not to be used for remote deployments, for security reasons.
• For those wanting to deploy this site on a production server, stay tuned.