Home - Hillsborough-Transit-Authority/onebusaway-application-modules GitHub Wiki

This is project is OneBusAway software modified for HART's original Tampa, FL deployment.

NOTE - This system has since been moved to Amazon EC2.

If you're looking for the main OneBusAway (OBA) project, please see the OneBusAway Application Suite wiki.

The below instructions discuss the specific deployment of the OBA software to the OBA Tampa server infrastructure. For more general instructions on how to compile the web applications using Eclipse, please see the OBA Developer Installation Guide.

You can find the active OneBusAway instance for Tampa, FL at http://tampa.onebusaway.org.

The OneBusAway software is current running on HART's virtualized servers.

Google Doc for above drawing is here.

The OBA Tampa deployment consists of the following components:

• OneBusAway (onebusaway-application-modules - this Github project)
• GTFS-realtime feed software - retrieves real-time transit data from the AVL system and formats it into GTFS-realtime format
• MySQL Database Server- holds user account information, as well as a cache of transit data
• XWiki Server - contains the text and images used in the OneBusAway desktop web interface

The following sections discuss the specific technical details and instructions for deploying and maintaining the above components of the OBA Tampa software system. At the bottom of the page, we include details for available third-party application programming interfaces (APIs), and well as details on available third-party apps.

As shown by the above architecture figure, data is exchanged between the different components of the system. This section contains information on the size and frequency of data exchange. Note that data exchange that happens within the same virtualized server doesn't have an impact on the net data input/output for that server. Also note that the frequency of data updates for the GTFS-realtime Generator application and OneBusAway server can be adjusted.

The GTFS-realtime Generator issues a JDBC query to the OrbCAD SQL Server to retrieve the current AVL data, and formats it according to the GTFS-realtime spec.

• Frequency - SQL query is currently executed every 5 seconds.

• Data Size - Request = Unknown, Response = Unknown

The OneBusAway Tomcat Server issues a HTTP request to the HART OrbCAD SQL Server to retrieve the GTFS-realtime Trip Updates and Vehicle Positions Protobuf files.

• Frequency - OneBusAway currently retrieves updated GTFS-realtime data every 15 seconds.

• Data Size - Request = Unknown, Response = (tripUpdate.pb at 8kB + vehiclePositions.pb at 9kB) = 17kB total

The many different OBA clients can all request information about static or real-time transit data from the OneBusAway Tomcat Server via HTTP, and receive a response.

• Frequency - Based on rate that clients decide to query OBA

• Data Size - Request = Unknown, Response = Unknown

• [In House Deployment Instructions](https://github.com/Hillsborough-Transit-Authority/onebusaway-application-modules/wiki/Local Deployment)
• [Cloud Deployment Notes](https://github.com/Hillsborough-Transit-Authority/onebusaway-application-modules/wiki/Cloud Deployment)

We're using our HART-GTFS-realtime-Generator software to make AVL data available to OBA via a GTFS-realtime feed. This software also runs on the same server as OBA, but uses an embedded Jetty web server running on port 8088.

To deploy a new version of the HART-GTFS-realtime-Generator software, the following two updated files should be placed in the C:\OneBusAway\GTFS-realtimeGenerator\application folder on the server:

• cutr-gtfs-realtime-hart-1.0.1.jar - Java file that contains the HART-GTFS-realtime-Generator software (file name and link to file on Github will depend on version number)
• cutr-gtfs-realtime-hart-autorun.bat - batch file that configures and starts the HART-GTFS-realtime-Generator software (The .bat file executes the cutr-gtfs-realtime-hart-1.0.1.jar file) (note that when a version number changes, you need to update this bat file to point to the new JAR file name). Note that you can change how often the GTFS-realtime feed refreshes the transit info from HART's system by changing the --refreshInterval=5 value (units is seconds) in this file.

Currently, cutr-gtfs-realtime-hart-autorun.bat is executed on server startup via a Windows Task "GTFS-realtime".

To test the GTFS-realtime feed, you can see the output in plain text format by visiting the below two links:

• http://localhost:8088/trip-updates?debug - For estimate arrival time updates
• http://localhost:8088/vehicle-positions?debug - For vehicle positions

NOTE: Apps should not use these URLs to retrieve GTFS-realtime data - see the OBA Tampa 3rd Party Developer Page for the URLs that developers should use

To change how often the OneBusAway software refreshes its real-time info from the GTFS-realtime feed, you need to change the data-sources.xml file in the onebusaway-transit-data-federation-webapp - for example:

<bean class="org.onebusaway.transit_data_federation.impl.realtime.gtfs_realtime.GtfsRealtimeSource">
    <property name="tripUpdatesUrl" value="http://localhost:8088/trip-updates" />
    <property name="vehiclePositionsUrl" value="http://localhost:8088/vehicle-positions" /> 
    <!-- Optionally set the refresh interval - how often we query the URLs, in seconds (default=30) -->
    <property name="refreshInterval" value="15" />
</bean>

...would refresh the real-time data in OBA every 15 seconds.

Note that the current data-sources.xml file in the onebusaway-transit-data-federation-webapp assumes that the GTFS-realtime feed is running on the same server as OBA, hence the localhost entry. If the GTFS-realtime feed is moved to another server, this same config file will need to be updated with the new servername. You may be able to modify this file within an existing compiled onebusaway-transit-data-federation-webapp WAR archive and redeploy the WAR to the Tomcat server. If this approach doesn't work, you'll need to recompile the onebusaway-transit-data-federation-webapp application using the approach documented on the main OBA app modules developer installation guide wiki, and then redeploy the newly compiled application to the Tomcat server.

If the HART OrbCAD database server moves to a new servername (or database server credentials change), you can stop the existing GTFS-realtime feed, and then edit the file C:\OneBusAway\GTFS-realtimeGenerator\config.properties and change the host field to a new value. When you restart the GTFS-realtime application, it should pick up these new values.

All OBA Tampa desktop browser website content (e.g., text, images, etc.) is managed through an XWiki instance (XWiki Enterprise 5.1) running in the same Tomcat instance as OBA. It is deployed as a WAR file in Tomcat under the path xwiki, and therefore starts and stops when Tomcat is started and stopped.

NOTE: if the XWiki port number or IP/servername is changed, the onebusaway-webapp data-sources.xml file will also need to be changed and redeployed to point to the new port number and server. Since a remote call is made to the XWiki servername from the user's web browser, the XWiki servername in the onebusaway-webapp data-sources.xml file CANNOT be localhost. Therefore, even if the image is moved as a whole to a new server, the XWiki servername will still need to be updated to the new public facing XWiki servername. After modifying the file you'll need to recompile the onebusaway-webapp using the approach documented on the main OBA app modules developer installation guide wiki, and then redeploy the newly compiled application to the Tomcat server.

We are currently using MySQL Community Server (installed via the MySQL Installer for Windows)) as a database server for all user account info and the transit data cache, running on HART's VM database server (.44 machine) on port 3306. The MySQL server is set up to start via a Windows Service MySQL-OneBusAway that starts at Windows startup.

For the OBA mobile apps to work with OneBusAway, the following keys must exist in the data-sources.xml file for the opentripplanner-api-webapp:

• Android: v1_BktoDJ2gJlu6nLM6LsT9H8IUbWc=cGF1bGN3YXR0c0BnbWFpbC5jb20=
• iPhone: org.onebusaway.iphone
• Windows Phone: v1_C5+aiesgg8DxpmG1yS2F/pj2zHk=c3BoZW5yeUBnbWFpbC5jb20=

These keys have been added to the OBA Tampa server instance.

Every time HART updates their GTFS data, we need to follow the following steps:

1. Delete any current files in the directory C:\OneBusAway\bundle on the computer where you're building the bundle.

2. Build the OBA graph with the new HART data on your computer

   • Put new HART GTFS data in the directory C:\OneBusAway\HART_GTFS\google_transit.zip.
   • Execute org.onebusaway.transit_data_federation.bundle.FederatedTransitDataBundleCreatorMain in the OBA project onebusaway-transit-data-federation-builder with the Program Arguments of C:\OneBusAway\HART_GTFS\google_transit.zip C:\OneBusAway\bundle and VM arguments of -Xmx4000m. This will produce new bundle files in the directory C:\OneBusAway\bundle.

3. Remove the .41 machine from the load balancer, to avoid interruption user traffic during the update.

4. Remote Desktop into the server .41

5. Right-click on the "OneBusAway - Tomcat 6 Port 80" icon in the status bar in the lower-right hand corner of the screen, and select "Stop Service." This will stop the OBA service and the http://tampa.onebusaway.org website will not be available on that machine until the service is restarted. You must wait for the service to completely stop, so Tomcat releases the lock on the old transit data files.

6. Delete any files in the directory C:\OneBusAway\bundle on the server. Copy all files from the directory C:\OneBusAway\bundle on your computer and paste them using Remote Desktop into the directory C:\OneBusAway\bundle on the .41 server (NOTE - you cannot just overwrite the files on the server, as not all OBA information will be updated. You must delete all old files and copy the new files into a clean directory).

7. In Remote Desktop on .41, right-click on the "OneBusAway - Tomcat 6 Port 80" icon in the status bar again, and select "Start Service." This will start the OBA service and the http://tampa.onebusaway.org website on that machine should become available again with the newly loaded bundle data. Note it may take the server up to two minutes to fully start.

Then, repeat steps #3-7 for machines .42 and .43.

Please see the wiki page Tampa - Creating Service Alerts for detailed instructions on creating service alerts that will be seen by OneBusAway users in Tampa.

We expect the main OneBusAway project (that this project is forked from) will continue to be improved over time. We want to be able to deploy any improvements to the main project here in Tampa.

To make this easy, we are using two branches in OBA Tampa: master and develop. We also have three Git remotes registered in the .45 development machine: origin (this Github repo), upstream (the main OBA project), and usf (the legacy USF repo that was used during the OBA Tampa pilot project. The usf remote is only maintained for use with future research-based modifications of OBA.

In the .45 development machine and this Github repo, master should remain a clean copy of the upstream/master branch. develop is several commits ahead of master, which includes Tampa-specific modifications, such as changing the example search text to be Tampa-specific, as well as a Google Analytics key specific to Tampa.

Therefore, to merge improvements from the main OBA project to OBA Tampa, we:

1. pull updates from upstream\master to the local .45 machine master branch,
2. rebase the develop branch on the master, and
3. clean, build, and deploy the new and improved web apps from the develop branch.

Finally, to update this fork, we push all changes from the .45 machine to this repo (i.e., origin on the .45 development machine). Assuming there are no conflicts during the rebase, this allows us to maintain the Tampa-specific version of OBA in the develop branch, with the master remaining a copy of upstream/master. If there are conflicts during the rebase, they will need to be manually resolved.

The above design also lets us easily submit improvements back to the main OBA project. For example, we may fix a problem in the OBA Tampa code that is common to all other OBA instances. We want to submit this in a pull request so that the improvement can be merged into the main OBA project.

To do this, we'll want to follow these steps:

1. Create a new branch issueX off of the master branch. This makes sure that only the improvement we want to contribute is included (and not all the OBA Tampa changes).
2. Make the change to the code, and commit it, including a description of the issue fix (if the change is already in an atomic commit in the develop branch, you can also Git cherry-pick it into this new issue branch). Ideally, this should include referencing an issue number that describes the issue in detail on the main Github OBA issue tracker.
3. Push the new issue branch, including the commit with the improvement, to this Github repo (i.e., origin from the .45 development machine).
4. Open a Github pull request to merge this new issueX branch into the main OBA master branch.

There are two interfaces provided by the software deployed on the server tampa.onebusaway.org that can be used by 3rd party apps to retrieve real-time transit information:

1. GTFS-realtime feed
2. OneBusAway REST API

Please see the Tampa - Third Party App Interfaces page for details.

There are a few known limitations to the load-balanced configuration being used in OBA Tampa:

1. Service Alerts - service alerts are not persisted back to the main database used by OBA, but instead maintained internally in the OBA web app. This means that service alerts must be manually entered on each OBA clone behind the load balancer one-by-one for them to appear in all user requests. Route-specific service alerts are not currently funcitonal (see Tampa - Creating Service Alerts for more info).
2. XWiki content - the XWiki servers (one per clone) are set up as a cluster, which means that when one is updated (and the update is applied to the database) the others should refresh their cache from the database, so they all display the updated information. We have found that this feature only works sporadically. In most cases, we have to refresh the cache manually. To do this, you can append ?refresh=true to the URL of the page that you are editing to force that XWiki clone to update. For example, if you just edited the "Contact Us" page on the .41 machine (http://10.19.80.41/xwiki/bin/view/Main/ContactUs), and .42 and .43 aren't showing the updated content, you can visit the URLs http://10.19.80.42/xwiki/bin/view/Main/ContactUs?refresh=true and http://10.19.80.43/xwiki/bin/view/Main/ContactUs?refresh=true to refresh the cache on those two clones. You may need to hit the browser refresh button once to force the cache refresh. This technique is preferred since it doesn't cause any interruption to the users. If this technique doesn't work, the caches will be refreshed if you restart Tomcat. In this situation, the clones can be taken off the load balancer and refreshed one-by-one, so there is no interruption to the end users.
3. Load balancer configuration - the load balancer must be configured for "sticky routes", so that two back-to-back requests from the same client go to the same server. This is needed so an admin can remotely log into XWiki to make wiki changes on the web site, as well as to make sure that when a user clicks on a service alert header they are directed to more information about the service alert (since UUIDs define each service alert, and per #1 above service alerts aren't persisted back to the main database but maintained per clone).
4. Access to the MySQL database is required at all times - the MySQL database must remain accessible at all times for OBA to function properly. More information is available on this issue page.
5. Route-specific service alerts do not work - see the bottom of the Creating Service Alerts page, and discussion on OBA Dev list.