The OneBusAway Application Suite Join the OneBusAway chat

A project of the non-profit Open Transit Software Foundation!

The OneBusAway application suite's primary function is to share real-time public transit information with riders across a variety of interfaces:

• Wayfinder - A high-performance web application built with with the SvelteKit JavaScript web app framework
• OneBusAway Web - A variety of web interfaces to transit data
  • A standard web interface to transit data, including maps and stop pages with real-time info
  • Sign-mode - Same information as the standard web interface, but in a large format for large displays (e.g., large televisions)
  • A mobile-optimized version of the web interface for smart phone mobile browsers
  • A text-only version of the web interface for more-basic mobile browsers
• OneBusAway REST API - A RESTful web-service that can be used to quickly write applications built on top of transit data. This API powers the following apps:
  • OneBusAway iOS (iPhone)
  • OneBusAway Android
  • OneBusAway Alexa (for Amazon Echo, etc.)
• OneBusAway GTFS-realtime export - A bulk export of all trip updates (predictions), vehicle positions, and service alerts for a transit system in the GTFS-realtime format.
• OneBusAway Watchdog - A module hosting webservices for monitoring realtime data

Watch the YouTube video for more information.

Getting Started

Here are the high-level steps you'll need to take to launch the OneBusAway mobile apps in your area:

1. Get your schedule transit data in the GTFS format
2. Have an AVL system that produces arrival estimates (Note: we're working removing this requirement - contact us if you're interested. Alternatively, you may be able to use other open-source projects, such as The Transit Clock, to go directly from raw vehicle locations to arrival times that are shared via GTFS-realtime and SIRI - this would replace Steps 2 and 3.)
3. Implement a GTFS-realtime or SIRI real-time data feed (We also support other formats)
4. Set up a OneBusAway server
5. Do some quality-control testing of arrival times
6. Request to be added as a OneBusAway region

See the multi-region page for more details.

Setting up a OneBusAway server

There are two options for setting up your own OneBusAway instance:

• Configuration and Deployment Guide for v2.x - Designed to provide a comprehensive deployment method for users who wish to set up a simple OneBusAway application with minimal configurations.
• onebusaway-docker (Under development) - A community-supported Docker configuration for OneBusAway v2.x is currently under development.

Development Instructions with Docker

docker compose up builder

# Now, open another window or tab and continue running commands:

# acquaint yourself with the make options
bin/make --help 

# build the project
bin/make

# now you have built all of the OBA artifacts, which can be found in the `/root/.m2/repository` directory.

# enter the docker container and look around
bin/shell 
ls /root/.m2/repository # this runs inside the docker container

# exit the docker container
exit 

# Build a data bundle, which will power the OBA server:
bin/build_bundle

# Finally, copy all of the built WAR resources into /usr/local/tomcat
bin/copy_and_relaunch

# wait a few seconds for everything to spin up...

Finally, verify that everything works as expected!

• Check out the Tomcat Web App Manager at http://localhost:8080/manager/html (user/pass: admin/admin) to verify that your OBA WARs deployed correctly
• Check out the config.json API endpoint to verify that everything built correctly: http://localhost:8080/onebusaway-api-webapp/api/where/config.json?key=test
• If the server isn't loading, Ctrl+C the Docker container to terminate it, then relaunch it, and everything should work fine.

GTFS Data

By default, the development server is configured to use static and real-time data from the Seattle area transit agency, King County Metro.

Change your Data Source, Step by Step

1. Delete the contents of ./docker_app_server/bundle (i.e. run the command rm -rf ./docker_app_server/bundle/*)
2. Update the GTFS_URL value in docker-compose.yml (See Static Data Changes for more)
3. Update the contents of ./docker_app_server/config/onebusaway-transit-data-federation-webapp-data-sources.xml as described in Realtime Data Changes
4. In a separate terminal, launch the builder service: docker compose up builder
5. From the root of the repository run the following commands:

• bin/make - Build the project (probably unnecessary, but better safe than sorry!)
• bin/build_bundle - Create a new data bundle
• bin/copy_and_relaunch - Copies the latest JAR and WAR files, as well as the contents of ./docker_app_server/config into $CATALINA_HOME

1. If necessary, restart the builder service: Ctrl+C and then docker compose up builder

Static Data Changes

./docker-compose.yml:

• Change GTFS_URL to your static GTFS URL: GTFS_URL=https://www.soundtransit.org/GTFS-KCM/google_transit.zip
• Change your time zone (TZ) to match the time zone of the agency specified in your GTFS data: TZ=America/Los_Angeles

Realtime Data Changes

In the file ./docker_app_server/config/onebusaway-transit-data-federation-webapp-data-sources.xml, change the following properties:

• tripUpdatesUrl
• vehiclePositionsUrl
• alertsUrl
• agencyId

Note: if the GTFS-RT feeds require a header-supplied API key, also modify the headersMap property thusly:

<property name="headersMap">
  <map>
    <entry key="{API KEY PROPERTY NAME}" value="{API KEY PROPERTY VALUE}" />
  </map>
</property>

for example:

<bean class="org.onebusaway.transit_data_federation.impl.realtime.gtfs_realtime.GtfsRealtimeSource">
    <property
      name="tripUpdatesUrl"
      value="https://gtfsbridge.spokanetransit.com/realtime/TripUpdate/TripUpdates.pb"
    />
    <property
      name="vehiclePositionsUrl"
      value="https://gtfsbridge.spokanetransit.com/realtime/vehicle/VehiclePositions.pb"
    />
    <property
      name="alertsUrl"
      value="https://gtfsbridge.spokanetransit.com/realtime/Alert/Alerts.pb"
    />
    <property name="refreshInterval" value="30" />
    <property name="agencyId" value="STA" />
    <property name="headersMap">
      <map>
          <entry key="X-API-KEY" value="12345" />
      </map>
    </property>
</bean>

Debugging

VSCode

0. Make sure that you have completed all of the earlier steps and that this endpoint loads in your browser: http://localhost:8080/onebusaway-api-webapp/api/where/config.json?key=test
1. Install these extensions:

• Debugger for Java
• Extension Pack for Java

2. Set breakpoints in the code file that you want to debug. If you're just getting started, we recommend that you set a breakpoint in onebusaway-api-webapp/src/main/java/org/onebusaway/api/actions/api/where/ConfigAction.java in the index() method.
3. Open the Run and Debug tab in VSCode, make sure that the debug target dropdown lists Debug (Attach).
4. Click the Start Debugging button.
5. Open your web browser and navigate to the API action where you have set a breakpoint. If you have set a breakpoint in ConfigAction.java, navigate to http://localhost:8080/onebusaway-api-webapp/api/where/config.json?key=test

Deploy OneBusAway

• Download pre-built JARs and WARs: https://developer.onebusaway.org/downloads
• Terraform/Open Tofu/Infrastructure as Code: https://github.com/onebusaway/onebusaway-deployment
• Docker
  • Pre-built images: https://hub.docker.com/r/opentransitsoftwarefoundation/
  • Instructions: https://github.com/onebusAway/onebusaway-docker

Deployments

OneBusAway is used in a number of places:

• http://pugetsound.onebusaway.org - the original Seattle-area deployment that started it all
• http://tampa.onebusaway.org - a deployment in Tampa, Florida
• http://bustime.mta.info - real-time info for NYC MTA buses

Check out the full list on the OneBusAway Deployments page. Check out the main project page at http://onebusaway.org.

Download

• Latest Stable Release

Build and Deploy OBA Artifacts to Maven Central

1. Set up your environment, including GPG
   • Maven Central documentation
   • Some helpful information elided by Sonatype
2. Run the command mvn deploy -DskipTests
3. Upload the Zip file at ./target/central-publishing/central-bundle.zip to Maven Central's publishing page.
   • The Zip file is about 600MB in size. Be sure to have a fast, reliable connection.

Open questions and issues:

• I haven't figured out why I cannot get the mvn deploy command to upload to Maven Central automatically.
• We need to automate deployment to Maven Central via GitHub Actions eventually, too.

Developer Information

• Installation Guide - How to set up your own OneBusAway instance using the code and Eclipse.
• Real-time Data Compatibility - Have a real-time transit data source (e.g., GTFS-realtime, SIRI)? Check out this page to see how you can make it work with OneBusAway.
• Troubleshooting tips - Having problems? Check out this guide.
• Mobile App Design Considerations - Want to create a mobile app for OneBusAway? Check out this page first.
• Multi-Region - OneBusAway is launching in new cities! Check out this page to learn how to launch the OneBusAway apps in your city.
• Contribution Guide - Information for developers on how to contribute code to OneBusAway, including general code conventions, how to submit patches, etc.
• Project Governance - Guide to OneBusAway project governance
• Maven Repository Info - Where the release and snapshot artifacts of OneBusAway libraries are found.
• Mailing lists:
  • Developer discussion list
  • User discussion list

Contact Info

There are lots of ways to get in touch with us.