This guide is designed to provide a comprehensive deployment method for users who wish to set up a simple OneBusAway application with minimal configurations. It is primarily intended for use cases that would need to be more permanent than just using the quick start version of OneBusAway. Unlike quick start, this solution boots with the server automatically with no additional configuration required.
Note on Software Versions
When using this guide, be certain to use the exact same versions of all software mentioned here. Any discrepancies between this guide and your actual installation will more than likely result in complicated errors and, ultimately failure. Follow the instructions exactly and there should be no issues.
Server Minimum Requirements
The minimum system requirements for your server depend on the size of the transit agency that the deployment is for. Failure to select a server with sufficient processing power and, more importantly, memory, will result in the Tomcat service, or the server itself needing a reboot several times a day. This guide is written for a small to medium sized municipal transit agency, with about 64 routes, 317 vehicles and 2414 stops. For this deployment I am using a virtual server with 2.0 GHz of processor power and 2048 GB of memory.
Server Operating System
This guide assumes the end user already knows how to set up a server (virtual or dedicated) using the Debian 8 operating system. We need to start with a clean installation of Debian 8 with no extra anything, not even the Debian desktop environment.
When setting up Debian 8 using the installer, be certain not to install any additional components except for the SSH server and standard system utilities. You can probably get away with including more on the server but this guide is written with a clean, lightweight server environment in mind and making your server the same will help insure success. Also, the less that is running on the server, the more resources available for OneBusAway.
You will need access to the root user to follow this guide. All commands are executed as the root user.
Installing Required Software
Using Debian 8, the following software must be installed:
OpenJDK Runtime Environment 7
This is the open source version of the Java 7 JDK Runtime Environment. To install it run the following command:
apt-get install openjdk-7-jdk
Tomcat 7
This software is used to serve the OneBusAway web application. To install it run the following command:
apt-get install tomcat7
Git
This software is required for downloading the source code from the OneBusAway repository on GitHub. To install it run the following command:
apt-get install git
Maven 3
Maven is used to build the OneBusAway application from the source code. To install it run the following command:
apt-get install maven
MySQL Server
The MySQL Server is used to store OneBusAway user data and API keys. To install it run the following command:
apt-get install mysql-server
During the install process, you will be prompted to create a password for the root MySQL user. Make sure to take note of the password you set because it will be needed later.
Acquiring the Source Code
Now that all of the required supporting software is installed, we must now download the source code from the OneBusAway repository on GitHub. To do this, run the following commands in sequence:
mkdir /oba
cd /oba
git clone https://github.com/OneBusAway/onebusaway-application-modules.git
Checking Out the Right Version
Since we just cloned a git repository we need to direct git to check out the code for the version of OneBusAway that we want. In this guide we will be using version 1.1.18. To do this, run the following commands in sequence:
cd /oba/obaonebusaway-application-modules
git checkout onebusaway-application-modules-1.1.18
Build It
Now we can build the OneBusAway software from the source code with Maven. To do this run the following command:
mvn clean install
This will take a while, so don’t worry if it doesn’t build immediately. Give the build at least 15 minutes to run. When this is complete the console should show a summary of the build. Every item in the list should indicate the build for that item was successful. If it wasn’t successful, do not proceed, start over and try again.
Download the Transit GTFS Data From the Transit Agency
Next we need to download the GTFS Data from the transit agency. With this data we can build the Transit Data Bundle that OneBusAway will use as a data source. To do this run the following commands in sequence:
cd /oba
wget http://transitagency.example.com/gtfs.zip
In the proceeding command, replace http://transitagency.example.com/gtfs.zip with the full URL of the GTFS from your respective transit agency. Take note of the actual file name being downloaded, as it will be needed later.
Build the Transit Data Bundle
Now it is time to build the Transit Data Bundle that OneBusAway will use to display route and schedule information. To do this run the following command:
java -Xss8192M -classpath .:/oba/onebusaway-application-modules/onebusaway-transit-data-federation-builder/target/* org.onebusaway.transit_data_federation.bundle.FederatedTransitDataBundleCreatorMain /oba/gtfs.zip /oba/gtfs
In the above command, replace gtfs.zip with the name of the GTFS data file that was downloaded earlier. The extension of the file should end with .zip. This process will take a while to run. When it is complete you should see “Shutting down EHCache CacheManager” with no major errors before it.
Download the MySQL Connector Java Library
Next we need the MySQL Connector Java Library. This will allow OneBusAway to use the MySQL database. You can download the library from https://dev.mysql.com/downloads/connector/j/. To do this, run the following commands in sequence:
cd /oba
wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-5.1.46.tar.gz
tar -zxvf mysql-connector-java-5.1.46.tar.gz
mv mysql-connector-java-5.1.46/mysql-connector-java-5.1.46-bin.jar .
rm -rf mysql-connector-java-5.1.46.tar.gz
rm -rf mysql-connector-java-5.1.46
Create the MySQL Database
Now we are going to create the database that OneBusAway will use to store user and API data. To do this run the following command:
mysql -p -e "CREATE DATABASE oba; GRANT ALL PRIVILEGES ON oba.* TO 'oba'@'localhost' IDENTIFIED BY 'newPassword';"
In the above command, replace newPassword with something secure. This will be the password for the MySQL user oba who will only have access to the database oba. When prompted for a password, enter the password of the MySQL root user that you set while installing MySQL.
Stop the Tomcat7 Service
To prepare for deployment, we need to stop the Tomcat 7 service. To do this run the following command:
service tomcat7 stop
Copy the Web Application Resource Files into Tomcat
Next we need to copy the Web Application Resource file into Tomcat’s webapps directory. To do this run the following commands in sequence:
cd /var/lib/tomcat7/webapps/ROOT
rm -rf *
mv /oba/onebusaway-application-modules/onebusaway-combined-webapp/target/onebusaway-combined-webapp-1.1.18-full.war ./ROOT.war
jar xvf ROOT.war
Move the MySQL Connector Java Library
To allow OneBusAway to use MySQL we need to copy the library we previously downloaded to a directory where it can access it.
cd /var/lib/tomcat7/webapps/ROOT/WEB-INF/lib
mv /oba/mysql-connector-java-5.1.46-bin.jar .
Create the Configuration File
Now we need to create a configuration file that OneBusAway will use to reference the various data sources it requires to operate. To do this run the following command:
nano /var/lib/tomcat7/webapps/ROOT/WEB-INF/classes/data-sources.xml
Once in the editor add the following text:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-2.5.xsd">
<!-- Database Connection Configuration -->
<bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
<property name="driverClassName" value="com.mysql.jdbc.Driver" />
<property name="url" value="jdbc:mysql://127.0.0.1/oba?characterEncoding=UTF-8" />
<property name="username" value="oba" />
<property name="password" value="newPassword" />
</bean>
<bean class="org.onebusaway.container.spring.SystemPropertyOverrideConfigurer">
<property name="order" value="-2" />
<property name="properties">
<props>
<prop key="bundlePath">/oba/gtfs</prop>
</props>
</property>
</bean>
<bean class="org.onebusaway.transit_data_federation.impl.realtime.gtfs_realtime.GtfsRealtimeSource">
<property name="tripUpdatesUrl" value="http://transitagency.example.com/realtime/TripUpdate/TripUpdates.pb" />
<!-- Optionally set the Vehicle Positions endpoint -->
<property name="vehiclePositionsUrl" value="http://transitagency.example.com/realtime/Vehicle/VehiclePositions.pb" />
<!-- Optionally set the Service Alerts endpoint -->
<property name="alertsUrl" value="http://transitagency.example.com/realtime/Alert/Alerts.pb" />
<!-- Optionally set the refresh interval - how often we query the URLs, in seconds (default=30) -->
<property name="refreshInterval" value="10"/>
<!-- Optionally configure the agency id we use to match incoming real-time data to your GTFS data -->
<property name="agencyId" value="MyAgency" />
</bean>
<bean class="org.onebusaway.container.spring.PropertyOverrideConfigurer">
<property name="properties">
<props>
<prop key="cacheManager.cacheManagerName">org.onebusaway.transit_data_federation_webapp.cacheManager</prop>
<prop key="defaultWebappConfigurationSource.googleMapsApiKey">YOUR-GOOGLE-MAPS-API-KEY</prop>
</props>
</property>
</bean>
</beans>
In the above XML code you will need to replace newPassword in the SQL settings with the password you chose for the oba user. You will also need to set the URLs of the GTFS real-time data feeds to that of your transit agency. Next, set an ID for the transit agency by replacing MyAgency. Finally, if you plan to have your OBA instance served from a domain name or public IP address you will need to generate a Google Maps API key and replace YOUR-GOOGLE-MAPS-API-KEY. Information about how to generate a Google Maps API key can be found at https://developers.google.com/maps/documentation/javascript/get-api-key.
Configure Tomcat to use More Memory
By default Tomcat uses a very small amount of memory. Usually this is not enough memory to run OneBusAway. To fix this run the following commands:
nano /etc/default/tomcat7
Change the line that says
JAVA_OPTS="-Djava.awt.headless=true -Xmx128m -XX:+UseConcMarkSweepGC"
to
JAVA_OPTS="-Djava.awt.headless=true -Xmx1792M -XX:+UseConcMarkSweepGC"
Note the Xmx variable; this variable is used to indicate to Tomcat exactly how much memory it is allowed to use. You may need to tweak this variable dependent on the size of the transit agency.
Start the Tomcat7 Service
Finally we can start the Tomcat7 Service to see if everything worked. In a second SSH window you may want to run the following command so that you can watch the output of the Tomcat7 service as OneBusAway starts up for the first time:
tail -f /var/log/tomcat7/catalina.out
To actually start the Tomcat7 Service simply run this command:
service tomcat7 start
Visit Your OneBusAway Installation from a Web Browser
Now point your favourite web browser to http://myoba.example.com:8080 —replacing the domain name with your server’s host name or IP address, making sure to preserve the port number at the end. Once loaded on the browser OneBusAway will prompt you to set up an administrator account. Fill out the form. Once the account set up is complete you will see a page telling you how to customize the site itself. If you want to jump right into the data you can do so by visiting http://myoba.example.com:8080/where/standard —once again replacing the domain name as appropriate.
This article was written for the OneBusAway Project Wiki on GitHub.