OneBusAway Docker Images

This repository contains scripts and configuration for building version 2 of the OneBusAway Application Suite for use with Docker.

Deploying to a cloud provider?

Check out our onebusaway-deployment repository, which features OpenTofu (Terraform) IaC configuration for deploying OneBusAway to AWS, Azure, Google Cloud Platform, Render, Kubernetes, and other platforms.

Deploying Docker Images

The 'simplest' way to deploy to services compatible with Docker image deployment is by creating immutable Docker images with your static data bundle pre-generated inside of the image. See deployment-examples/README.md for more information.

Deploy to Render

Render is an easy-to-use Platform-as-a-Service (PaaS) provider. You can host OneBusAway on Render by either manually configuring it or by clicking the button below.

Running in Kubernetes

Learn more about running OBA in Kubernetes in the dedicated README.

Running locally

To build bundles and run the webapp server with your own GTFS feed, use the Docker Compose services in this repository.

Building the app server

docker compose build oba_app

Building bundles

To build a bundle, use the oba_bundler service:

GTFS_URL=https://www.soundtransit.org/GTFS-rail/40_gtfs.zip docker compose up oba_bundler

This process will create all necessary bundle files and metadata, and all will be accessible in your local repo's ./bundle directory.

When the GTFS_URL is unspecified, oba_bundler will download and use the GTFS data for Davis, CA's Unitrans service. This can be used with the bin/validate.sh script to verify that the stack is working correctly.

docker compose up oba_bundler

Running the OneBusAway server

Once you have built an OBA bundle inside ./bundle, you can run the OBA server and make it accessible on your host machine with:

docker compose up oba_app

The container runs two web apps:

• onebusaway-api-webapp, hosted at http://localhost:8080/
  • Example API call: http://localhost:8080/api/where/agencies-with-coverage.json?key=TEST
• onebusaway-transit-data-federation-webapp, which does the heavy lifting of exposing the transit data bundle to the API webapp. It is an internal service: it listens only on 127.0.0.1:8081 inside the container and is deliberately not reachable from your host or the network. (Its remoting endpoint is an internal interface, not a public API, and must never be exposed. See Security.)
  • To poke at it for debugging: docker compose exec oba_app wget -qO- http://127.0.0.1:8081/onebusaway-transit-data-federation-webapp/

When done using this web server, you can use the shell-standard ^C to exit out and turn it off. If issues persist across runs, you can try using docker compose down -v and then docker compose up oba_app to refresh the Docker containers and services.

Using local GTFS files

If you have a local GTFS file instead of downloading from a URL, see the example-local-gtfs/ directory for a complete example that demonstrates how to build bundles using local GTFS files.

Inspecting the database

The Docker Compose database service should remain up after a call of docker compose up oba_app. Otherwise, you can always invoke it using docker compose up oba_database.

A database port is open to your host machine (on 127.0.0.1 only, since the development credentials are public), so you can connect to it programmatically using mysql:

mysql -u oba_user -p -h localhost:3306

Deployment

Published Images

You can find the latest published Docker images on Docker Hub:

• onebusaway-bundle-builder - This image is built from the bundler directory and contains the functionality needed to create a transit data bundle from a GTFS feed.
• onebusaway-api-webapp - This image is built from the oba directory and contains the functionality needed to run the OBA API webapp.

Security

The images are built to be safe by default, but a few things are the operator's responsibility:

• Only publish port 8080. The federation webapp's internal remoting endpoint is bound to loopback (127.0.0.1:8081) inside the container and is not served on 8080. Don't add a proxy inside the container's network namespace that forwards to 8081.
• Port 1234 (Prometheus JMX exporter) is unauthenticated. Keep it on a private network or loopback; don't publish it to the internet.
• Use real credentials. The passwords in docker-compose.yml, docker-compose.standalone.yml, the examples, and oba.yaml are public development placeholders, and those files bind database ports to 127.0.0.1 for that reason. docker-compose.prod.yml refuses to start until you provide MYSQL_ROOT_PASSWORD and MYSQL_PASSWORD. Never publish a database port to the internet.
• Don't set TEST_API_KEY in production.
• Built-in API keys. The image registers the API keys used by the official OneBusAway iOS and Android apps so that those apps work against your server. OneBusAway API keys identify and rate-limit clients; they are not a secret and do not protect data.
• Least privilege inside the container. Tomcat and the bundle build (which downloads and parses third-party GTFS data) run as the unprivileged oba_user. The Tomcat installation, rendered config files (which contain your database password), and the bundle are owned by root and are read-only to the webapp.
• Upgrading with USER_CONFIGURED=1? If you supply your own data-sources.xml for the API webapp, its transitDataService serviceUrl must now be http://127.0.0.1:8081/onebusaway-transit-data-federation-webapp/remoting/transit-data-service (it was localhost:8080). The container refuses to start if it sees the old URL.
• Rebuild regularly. Base images are pinned to patch versions and kept current by Dependabot; rebuilding picks up OS and JVM security updates.

Deployment Parameters

• Database
  • JDBC_URL - The JDBC connection URL for your MySQL or PostgreSQL database.
  • JDBC_DRIVER - The JDBC driver class name: com.mysql.cj.jdbc.Driver or org.postgresql.Driver
  • JDBC_USER - The username for your database.
  • JDBC_PASSWORD - The password for your database.
• GTFS (Optional, required only when using oba_app independently)
  • GTFS_URL - The URL to the GTFS feed you want to use.
  • BUNDLE_INPUTS_URL - URL to a bundle-inputs.json manifest for multi-input mode; specifies per-feed zips, agency IDs, and optional stop consolidation mapping. Mutually exclusive with GTFS_URL, GTFS_ZIP_FILENAME, and STOP_CONSOLIDATION_URL.
  • STOP_CONSOLIDATION_URL - (Single-zip mode only) URL to a stop-consolidation mapping file applied during bundle build. Mutually exclusive with BUNDLE_INPUTS_URL.
• GTFS-RT Support (Optional)
  • TZ - The timezone for the server. Ensure that the server's timezone matches the timezone specified in your static GTFS agency.txt file. The timezone format is the IANA standard, and a full list of timezones can be found on Wikipedia.
  • GTFS_RT_FEEDS - Preferred for configuring one OR many GTFS-RT feeds. A JSON array of feed objects; each object may contain tripUpdatesUrl, vehiclePositionsUrl, alertsUrl, refreshInterval, agencyIds (array), feedApiKey, and feedApiValue. Example: [{"tripUpdatesUrl":"https://a/trips","agencyIds":["unitrans"]},{"vehiclePositionsUrl":"https://b/veh","agencyIds":["kcm"]}]. When set, it takes precedence over the single-feed variables below.
  • ALERTS_URL - Service Alerts URL for GTFS-RT.
  • TRIP_UPDATES_URL - Trip Updates URL for GTFS-RT.
  • VEHICLE_POSITIONS_URL - Vehicle Positions URL for GTFS-RT.
  • REFRESH_INTERVAL - Refresh interval in seconds. Usually 10-30.
  • Specify one or the other:
    • AGENCY_ID_LIST - Your GTFS-RT agency IDs. These should match the IDs in your agency.txt file. Format: ["id1","id2"]
    • AGENCY_ID - Optional: Your GTFS-RT agency ID. Ostensibly the same as your GTFS agency ID.
  • Authentication (Optional)
    • Example: Specifying FEED_API_KEY = X-API-KEY and FEED_API_VALUE = 12345 will result in X-API-KEY: 12345 being passed on every call to your GTFS-RT URLs.
    • FEED_API_KEY - If your GTFS-RT API requires you to pass an authentication header, you can represent the key portion of it by specifying this value.
    • FEED_API_VALUE - If your GTFS-RT API requires you to pass an authentication header, you can represent the value portion of it by specifying this value.

The GTFS-RT related variables will be handled by the oba/bootstrap.sh script, which will set the config files for the OBA API webapp. If you want to use your own config files, you could set USER_CONFIGURED=1 in the oba_app service in docker-compose.yml to skip bootstrap.sh and write your config file in the container.

  oba_app:
    container_name: oba_app
    depends_on:
      - oba_database
    build:
      context: ./oba
    environment:
      # database configs are read from environment variables
      - JDBC_URL=jdbc:mysql://oba_database:3306/oba_database
      - JDBC_USER=oba_user
      - JDBC_PASSWORD=oba_password
      # change this to your GTFS url
      - GTFS_URL=https://unitrans.ucdavis.edu/media/gtfs/Unitrans_GTFS.zip
      # skip bootstrap.sh and use user-configured config files
      - USER_CONFIGURED=1