Public Repository

Last pushed: 5 months ago
Short Description
ROS Bag Database Web Application
Full Description

Bag Database

The Bag Database is a web-based application that monitors a directory for ROS bag
files, parses their metadata, and provides a friendly web interface for searching
for bags and downloading them. Its goal is to make it easy to catalog thousands
of bag files, search through them for relevant data such as topic names and message
types, view information about them, and download them.

Currently it is intended primarily for internal use. Any user can edit metadata
for bag files, and it is expected that users have access to the location where bags
are stored and will be manually uploading files there.


  • Directory Monitoring: It will watch a directory for any changes and
    automatically scan any bag files placed in that directory.
  • Full-text Searching: The Search field will search the text fields selected by the user in every
    bag file for any strings containing the provided text; it can search:
    • The bag's file name
    • The path leading to the bag on the filesystem
    • A user-provided description of the bag
    • The name of the physical location where the bag was recorded
      • (Either this must be manually entered or support for Google's reverse
        geocoding API must be enabled)
    • The name of the vehicle
    • The types of any messages used
    • The topics published
  • Filtering: Every column in the grid can by filtered by arbitrary values;
    click the down arrow on a column header to set a filter.
  • Folder View: Instead of a flat list of every bag file in the database, you
    can also see them in a hierarchical view mirroring their layout on the
    filesystem which indicates how many bags are under every path and can be
    filtered by filename.
  • Displaying Metadata: All of the same information you could obtain with
    rosbag info is extracted and stored so that it can be easily viewed for any
    bag file.
  • Message Types and Topics: You can also easily view all of the different
    message types and topics used in the bag file.
  • Displaying GPS Coordinates: GPS coordinates recorded in a bag file are
    extracted and stored, and you can view the path of the coordinates using
    either Bing Maps or an arbitrary WMTS tile map server.
  • Downloading: Every bag file can be downloaded from the interface without
    needing to find it on the host filesystem. Links to bag files can also be
    obtained by right-clicking on them.
  • Viewing Images: You can view the first image on any sensor_msgs/Image or
    sensor_msgs/CompressedImage topic by clicking on an icon next to the topic
    in the bag details window.
  • Viewing Image Streams: You can view any sensor_msgs/Image or
    sensor_msgs/CompressedImage topic as an embedded video stream by clicking
    on an icon next to the topic in the bag details window.
  • Tagging: Bags can be tagged and searched for with arbitrary metadata
    strings. Existing tags on arbitrary metadata topics in bag files will be
    automatically read.


The bag database is a Spring-based web application that requires Java 8.0 or later.
To compile it, you need JDK 8.0 or later and Maven 3.0.5 or later. To build a
WAR package, run:

mvn package

The preferred mechanism for running the bag database is as a
Docker container. To build the docker image, run:

cd src/main/docker
sudo docker build . -t bag-database:latest


If you're using Docker, upgrading to the latest version is as easy as pulling
the latest image and re-creating the container. Just run
docker pull swrirobotics/bag-database:latest, stop the old container, and set
up a new one as described below. Make sure you check the list of environment
variables to see what's been changed or added.


Docker (Preferred method)

The bag database can run standalone in order to demonstrate its functionality, but
if you do so it will have to rebuild the database every time it restarts. Instead
you should link it to an external database. PostgreSQL with PostGIS extensions is
the only supported database.

To start a PostgreSQL container with PostGIS support:

docker run -d \
    --name bagdb-postgres \
    -v /var/lib/bagdb-postgres:/var/lib/postgresql/data \
    -e POSTGRES_PASSWORD=letmein \
    -e POSTGRES_USER=bag_database \
    -e POSTGRES_DB=bag_database \

The bag database exposes port 8080 and expects to find bag files in a volume at /bags by default. You can run it like so:

docker run -d \
    -p 8080:8080 \
    -v /bag/location:/bags \
    --name bagdb \
    --link bagdb-postgres:bagdb-postgres \
    -e DB_DRIVER=org.postgresql.Driver \
    -e DB_PASS=letmein \
    -e DB_URL="jdbc:postgresql://bagdb-postgres/bag_database" \
    -e DB_USER=bag_database \
    -e METADATA_TOPICS="/metadata" \
    -e VEHICLE_NAME_TOPICS="/vehicle_name" \
    -e GPS_TOPICS="/localization/gps, /gps, /imu/fix" \

After the bag database has successfully started, the bag database should be available at Modify your Docker parameters as desired to expose it on a different port or set up HAProxy if you want to enable SSL or have it accessible via a subdirectory.


Several volumes within the Docker container may be useful to mount externally:


The location which will be monitored for bag files.


The location where Tomcat places its log files.

Environment Variables

Several environment variables can be set to configure the Docker container:


The default password for administrative access. If this is not set, one will be randomly generated and printed to the log file on initial startup.


The class name of the JDBC driver to use.


The password to use when connecting to the database.


The JDBC URL for connecting to the database.


The username to use when connecting to the database.


A Google API key that has permission to use the Google Maps GeoCoding API; this is necessary in order to resolve place names for GPS coordinates.


A comma-separated list of std_msgs/String topics in bag files that will be searched for metadata. The messages on the topic should be newline-separated tags that are made of colon-separated key/value pairs; for example:

name: John Doe

Every value will be read from every topic specified, but if there are any duplicate keys, the last-read values will take precedence.


Set this to true to use a WMTS tile map for displaying map imagery; set it to false to disable MapQuest. The default is true.


If USE_TILE_MAP is true, this URL will be used as a template for retrieving
map tiles. See the documentation for the url property of OpenLayers'
ol.source.XYZ class.
The default value is http://{a-d}{z}/{x}/{y}.jpg, which will
use the terrain map provided by Stamen.


The width of the tiles returned from the tile map in pixels. The default is 256.


The height of the tiles returned from the tile map in pixels. The default is 256.


Set this to true to use Bing Maps for displaying map imagery; set it to false to disable Bing. The default is false.


The API key to use when connecting to Bing Maps.


A comma-separated list of std_msg/String topics that will be searched for a vehicle name; the first one found will be used.


A comma-separated list of topics to search for GPS messages; the first one found will be used. Any message that has the following fields will work:

float64 latitude
float64 longitude
Header header

If there are no topics configured or none of them are found, it will try to use the first topic it can find that publishes the sensor_msgs/NavSatFix, gps_common/GPSFix, or marti_gps_common/GPSFix messages, in that order.


Set this to true to force the application to load non-minified versions of Javascript files. This will increase load times. The default is false.

As An Application Server Servlet

Only Tomcat 8.0 with Java 8.0 has been tested.

  1. Start up a PostgreSQL server; create an empty database and a user with access to it.
  2. Start up your application server and deploy the WAR file to it.
  3. The bag database will automatically create a directory at ${HOME}/.ros-bag-database and place its configuration inside there.
  4. Edit ${HOME}/.ros-bag-database/settings.yml and set your configuration, then restart the application. Here's an example of a valid config file; keys you don't want to set can be omitted.

     bingKey: PKnOQDvUxRJ0bEZdBH7m
     driver: org.postgresql.Driver
     googleApiKey: PKnOQDvUxRJ0bEZdBH7m
     - /localization/gps
     - /gps
     - /vehicle/gps/fix
     jdbcPassword: letmein
     jdbcUrl: jdbc:postgresql://bagdb-postgres/bag_database
     jdbcUsername: bag_database
     useBing: true
     useMapQuest: false
     - /vms/vehicle_name
  5. Look inside the log file at ${TOMCAT_HOME}/logs/bag_database.log to find the automatically-generated administrator password.

  6. Log in through the GUI and use the Maintenance panel to change the password.
  7. Note that in order for video streaming to work, ffmpeg version 3 or higher must be available on the system path.
Docker Pull Command