This guide will instruct you on how to install and run an instance of OneBusAway with your transit data. These instructions are intended to be thorough. If you are looking to get a quick demo instance of OneBusAway up-and-running with your data, check out our quick-start guide.
Check out the Downloads page for information about downloading the OneBusAway application modules.
At minimum you need to download onebusaway-transit-data-federation-builder.jar to build your transit data bundle and one of the webapps to host your OneBusAway instance.
OneBusAway has the concept of a transit data bundle, which is a collection of all the data artifacts for a transit agency (or group of transit agencies) in the internal format needed to power OneBusAway. These transit data bundles are typically created from external data such as GTFS feeds for transit data and OpenStreetMap data for the street network.
You will use the downloaded onebusaway-transit-data-federation-builder.jar to build the bundle, but the instructions are complex enough to deserve there own page:
OneBusAway is composed of a series of webapps that are designed to be run in a standard Java webapp container. You can choose whichever container you like, but we use Apache Tomcat by default. You can download it here:
Which webapps will you be running? For your first install, we recommend the onebusaway-combined-webapp.war, which combines all the major OneBusAway modules and functionality into one application. It includes the following modules:
Optionally, you can also download and run each OneBusAway webapp independently. This is useful when you just need one piece of OneBusAway functionality or want to do a more complex deployment. See special configuration details towards the end of this guide.
There is plenty of documentation on the web for installing webapps in your container of choice, so we will focus on specific configuration details here along with some tips for making things work with Apache Tomcat.
For the most part, configuration means editing instances of:
data-sources.xml
This configuration file is just a Spring bean configuration file and can be used to define beans and other resources that determine the configuration of your OneBusAway instance.
The webapps look for data-sources.xml in the WEB-INF/classes directory of each webapp by default. You can add the file to the war file directly or copy it into the exploded war directory structure.
OneBusAway is powered by a number of Java classes that provide different pieces of functionality. While we try to provide reasonable default behavior, you may wish to tweak OneBusAway at times. Many options can be set using a PropertyOverrideConfigurer to override specific class properties. Here is a quick example of the config youd add to your data-sources.xml file:
<bean class="org.onebusaway.container.spring.PropertyOverrideConfigurer">
<property name="properties">
<props>
<prop key="cacheManager.cacheManagerName">org.onebusaway.webapp.cacheManager</prop>
<prop key="defaultWebappConfigurationSource.googleMapsApiKey">ABC</prop>
...
</props>
</property>
</bean>
Here, each <prop/> entry specifies a key and a value. The key takes the form objectName.propertyName where objectName is a OneBusAway object and propertyName is a property of that object whose value youd like to override.
For the full list of documented configuration options, check out the list of configuration parameters auto-generated from the OBA source code.
As a Tomcat tip, you can override the location of the data-sources.xml to point to an external file instead, which is handy for injecting data-sources.xml without modifying the war. The key is to use a context xml file to define your webapp:
<Context path="onebusaway-webapp" docBase="path/to/onebusaway-webapp.war">
<Parameter name="contextConfigLocation"
value="classpath:application-context-webapp.xml file:path/to/data-sources.xml"
override="false" />
</Context>
For more info, see http://tomcat.apache.org/tomcat-5.5-doc/config/context.html
Its important to note that when you override contextConfigLocation in this way, youll need to additionally import the application-context-webapp.xml for the webapp you are attempting to configure (its normally included in the contextConfigLocation entry in web.xml for the webapp, but we lose it when we override). The location of the webapp is dependent on the webapps you are using:
If you are deploying the webapps individually, the locations are:
There is a minimum amount of configuration you need to perform to prepare the onebusaway-combined-webapp to be run. At minimum, you need to add the following entries to your data-sources.xml file:
<?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">
<!-- Define your bundle path. You can also do this externally with a "bundlePath" System property -->
<bean class="org.onebusaway.container.spring.SystemPropertyOverrideConfigurer">
<property name="order" value="-2" />
<property name="properties">
<props>
<prop key="bundlePath">/path/to/your/transit-data-bundle</prop>
</props>
</property>
</bean>
</beans>
The primary configuration element sets your bundlePath, pointing to your Transit Data Bundle. In addition, you might optionally consider changing the default database or adding a real-time data source.
For configuration details for each of user-interface components, see the specific configuration guides:
As mentioned previously, there may be situations where you do not wish to use the onebusaway-combined-webapp.war, but instead you wish to use the individual OneBusAway webapps. This gives you more power and flexibility for your installation, but the configuration is more complex as result. As described above, each webapp is configured through its own data-sources.xml file.
The key issue is that when you run the transit data webapp (onebusaway-transit-data-federation-webapp) independently of the user interface webapps (onebusaway-webapp, onebusaway-api-webapp, etc.), you will need to explicitly configure an RPC mechanism that allows the webapps to communicate with each other. Details are included below.
As described above, onebusaway-transit-data-federation-webapp does the heavy lifting of exposing the transit data bundle to the various user interface modules. As such, the main job of the data-sources.xml configuration file for the webapp is to point to the location of the bundle and the database where you installed the bundle. See Database Setup and Configuration for more specific details about database setup and configuration.
Here is a quick example:
<?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">
<!-- Define your bundle path. You can also do this externally with a "bundlePath" System property -->
<bean class="org.onebusaway.container.spring.SystemPropertyOverrideConfigurer">
<property name="order" value="-2" />
<property name="properties">
<props>
<prop key="bundlePath">/Users/bdferris/oba/local-bundles/puget_sound/current</prop>
</props>
</property>
</bean>
<!-- 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/org_onebusaway_agency_data?characterEncoding=UTF-8" />
<property name="username" value="USERNAME" />
<property name="password" value="PASSWORD" />
</bean>
</beans>
While each user interface webapp has specific configuration details, they share a lot of configuration in common. Specifically, we need to configure where they will find the onebusaway-transit-data-federation-webapp. Optionally, you can also override the default database configuration. For more details, see Database Setup and Configuration.
Each user interface webapp data-sources.xml should include these common entries:
<?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">
<!-- Wire up the transit data service. Adjust the url, including port and path, to match
your own deployment of the onebusaway-transit-data-federation-webapp -->
<bean id="transitDataService" class="org.springframework.remoting.caucho.HessianProxyFactoryBean">
<property name="serviceUrl" value="http://localhost:8080/onebusaway-transit-data-federation-webapp/remoting/transit-data-service" />
<property name="serviceInterface" value="org.onebusaway.transit_data.services.TransitDataService" />
</bean>
<!-- Optionally configure a user database -->
<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/org_onebusaway_users?characterEncoding=UTF-8" />
<property name="username" value="USERNAME" />
<property name="password" value="PASSWORD" />
</bean>
</beans>