Skip to content

Home

Jump to bottom Edit New page
Sean Barbeau edited this page Nov 21, 2013 · 68 revisions

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

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.

OneBusAway Tampa Website

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.

System architecture

HART OneBusAway Architecture

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.

Data Flow

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.

OrbCAD SQL Server -> GTFS-realtime Generator

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

GTFS-realtime Generator -> OneBusAway Tomcat Server

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

OneBusAway Tomcat Server -> OneBusAway clients (e.g., Android app, OBA Desktop browser, OBA smartphone browser, OBA text-only browser)

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

Deployment Instructions - For the OBA Tampa team

To deploy new WAR files to OBA Tampa server, use the environment set up on the .45 development machine. Then, build the projects using the instructions at the primary OBA Developer Installation page (be sure to follow the instructions for building the Google Web Toolkit components).

For the onebusaway-transit-data-federation webapp, onebusaway-api-webapp, and the onebusaway-webapp projects, you'll need to right-click on each and do "Export->WAR file". Select a place to save the WAR file on your local computer, and select the option to "Optimize for Tomcat v6". Rename the file onebusaway-api-webapp.war to api.war.

Remote desktop into the .41 machine.

Stop the Tomcat server by right-clicking on the OneBusAway - Tomcat port 80 icon in the lower-right hand corner of the screen and then clicking Stop service. Wait for the service to stop.

Delete the current WAR files and folders for onebusaway-transit-data-federation webapp, onebusaway-api-webapp (the api folder), and the onebusaway-webapp from the server directory C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps. Place the 3 new WAR files in this directory, and then re-start Tomcat by right-clicking on the OneBusAway - Tomcat port 80 icon in the lower-right hand corner of the screen and then clicking Start service. This may take several minutes for the server to initialize and the website to come back up. If 10 minutes or more have passed without a response, please check the Tomcat error log at C:\Program Files\Apache Software Foundation\Tomcat 6.0\logs.

Note: For some reason, when the onebusaway-webapp is redeployed Tomcat occasionally loses the registration of the context /onebusaway-webapp as the default root context (which allows us to see the OBA website at oba.gohart.org instead of oba.gohart.org/onebusaway-webapp). If you get the default Tomcat page at the root context when Tomcat comes back up, follow these steps:

  1. Shut Tomcat back down
  2. Make a backup copy of the file $TOMCAT_HOME/conf/server.xml
  3. Edit $TOMCAT_HOME/conf/server.xml to remove the <Context path="" docBase="onebusaway-webapp" debug="0" reloadable="true"></Context> text from the <Host /> element
  4. Start Tomcat
  5. Shutdown Tomcat
  6. Restore the backup of the $TOMCAT_HOME/conf/server.xml file by replacing the file you just edited with your backup.
  7. Restart Tomcat

The above should get Tomcat to re-map the /onebusaway-webapp context to the default root context, so you should see the OneBusAway homepage at the root context again when the server comes back up.

Repeat the above process for the .42 and .43 machines.

Adding real-time data (GTFS-realtime Feed)

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:

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.

XWiki Server

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.

Database 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.

Mobile App Server Configuration

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.

Maintenance Instructions - For the OBA Tampa team

Updating OBA with new GTFS data

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.

Creating OBA Service Alerts

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.

Merging improvements from the main OneBusAway project

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, and
  2. rebase the develop branch on the master.
  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.

Contributing improvements back to the main OBA project

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.

Third party App Interfaces

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.

Third party Mobile Apps

Information about third-party mobile apps for OneBusAway Tampa is available on the Tampa Third Party Mobile Apps page.

Add a custom footer
Add a custom sidebar
Clone this wiki locally