Skip to content
Switch branches/tags

Latest commit

* Update readme to new dev setup

* [CY-5603] Use version-less jar in dev setup

* Cleanup code and add docmentation

Git stats


Failed to load latest commit information.
Latest commit message
Commit time


vert.x 4.0.3 purple mongo 4.0.11 purple badge

This application represents the Cyface data collector software.

It is used to collect traffic data from Cyface measurement devices, such as our sensor box or our smartphone application.

Our smartphone SDK is available as GPL application for Android and iOS (or as Podspec) as well.

If you require this software under a closed source license for you own projects, please contact us.

Changes between versions are found in the Release Section.

The project uses Gradle as the build system. It is set up as a Gradle multi project build. There are two general categories of sub projects. One are executable programs fulfilling a certain task of the Cyface backend. Others are libraries shared by several Cyface executables. The executables are grouped in the sub-project executables while the libraries are grouped in libs. The following sections provide an overview about those projects.


All directly executable programs within this project


A program which provides the ability to collect data, as e.g. sent by the Cyface SDKs.

The following sections start with an explanation on how to set up all the required certificates. This is a necessary prerequisite for all the following steps. So DO NOT skip it.


The Cyface Data Collector provides keys you may use for testing and during development. Those keys are located in src/test/resources. To use them outside of Unit tests you need to copy them to an appropriate location. ATTENTION: DO NOT USE THOSE KEYS IN A PRODUCTION ENVIRONMENT. Since they are in our repository, they are openly available to everyone on the internet, so everyone can compromise security on your server if you use the default keys.

The Cyface Data Collector requires two keys to issue and authenticate JWT tokens for users trying to communicate with the service. Just place the appropriate files as private_key.pem and public.pem in secrets/jwt, right next to the docker-compose.yml file, or in the "working directory" selected in your run configuration in your IDE (e.g. data-collector/).

To generate new keys follow the instructions in the Vert.x documentation for Using RSA keys.


To build the docker container running the API simply execute ./gradlew :executables:collector:clean :executables:collector:build :executables:collector:copyToDockerBuildFolder. This builds the jar file which is then packed into the Docker container which is build afterwards. Please refer to the previous section about Certificates prior to building.

When you updated the Swagger UI make sure to clear your browser cache or else it might not update.


This section describes how to execute the Cyface Data Collector.

It begins with an explanation on how to run the Cyface Data Collector from a Docker environment. This is the recommended variant if you do not need to change the collector itself, but only need to develop against its API.

The section continues with an explanation on the supported configuration parameters. If you are not using the Docker environment, you will probably have to set a few of them to the correct values, before running the Cyface Data Collector.

The last two sections provide explanations on how to run the software directly from the terminal or from within an IDE such as Eclipse or IntelliJ. For these execution variants you need the parameters explained in the preceding section.

Running from Docker

After you did build the system (see Building above) simply run docker-compose up inside executables/collector/build/docker. This calls docker to bring up two Mongo-database containers and a container running the Cyface data collector API.

The Collector API is by default available via port 8080. This means if you boot up everything using the default settings, the Collector API is accessible via http://localhost:8080/api/v2.

ATTENTION: The docker setup should only be used for development purposes. It exposes the Cyface data collector as well as the ports of both Mongo database instances freely on the local network. Use docker-compose ps to see which ports are mapped to which by Docker. For using such a setup in production, you may create your own Docker setup, based on our development one.

Running without Docker

Running the Cyface data collector without Docker, like for example from the terminal or from within your IDE is a little more complex. It requires a few set up steps and command knowledge as explained in the following paragraphs.

Running a Mongo Database for Data and User Storage

Before you can run the Cyface data collector you need to set up a Mongo database.

If you use the Docker environment as explained above, this is done for you. If you run the Cyface data collector on your own, you are responsible for providing a valid environment, including Mongo.

The database is used to store the collected data and information about valid user accounts. For information on how to install and run a Mongo database on your machine please follow the tutorial. If you take the default installation, the default settings of the Cyface data collector should be sufficient to connect to that instance. ATTENTION: However be aware this is not recommended as a production environment.

Data Collector Arguments

The Cyface data collector supports a few parameters to fine tune the runtime. All of these parameters also provide reasonable defaults for a quick setup. The parameters are provided using the typical Vertx -conf parameter with a value in JSON notation.

The following parameters are supported:

  • jwt.private: The path of the file containing the private key used to sign JWT keys. This defaults to secrets/private_key.pem, which you should never use in production.

  • jwt.public: The path of the file containing the public key used to sign JWT keys. This defaults to secrets/public.pem, which you should never use in production.

  • http.port: The port the API is available at. This defaults to 8080.

  • The hostname under which the Cyface Data Collector is running. This can be something like localhost.

  • http.endpoint: The path to the endpoint the Cyface Data Collector is running. This can be something like /api/v2.

  • The port the management API is available at. This defaults to 13371.

  • mongo.userdb: Settings for a Mongo database storing credential information about all the users capable of logging into the system. This defaults to a Mongo database available at mongodb:// The value of this should be a JSON object configured as described here. In addition, if you use two different Mongo databases for credentials and data you should provide different values for the JSON key data_source_name.

  • admin.user: The username of a default administration account which is created if it does not exist upon start up. This defaults to admin. You must change this in a production environment.

  • admin.password: The password for the default administration account. This defaults to secret. You must change this in a production environment.

  • salt.path: The path to a salt file used to encrypt passwords stored in the user database even stronger. This defaults to secrets/salt. If the file does not exist a default salt is used. You should not do this in a production environment.

  • mongo.datadb: Settings for a Mongo database storing all data uploaded via the Cyface data collector. This defaults to a Mongo database available at mongodb:// The value of this should be a JSON object configured as described here. In addition, if you use two different Mongo databases for credentials and data you should provide different values for the JSON key data_source_name.

  • metrics.enabled: Set to either true or false. If true the collector API publishes metrics using micrometer. These metrics are accessible by a Prometheus server (Which you need to set up yourself) at port 8081.

Running from Command Line

To launch your tests:

./gradlew clean test

To package your application:

./gradlew clean assemble

To run your application:

./gradlew run --args="run de.cyface.collector.verticle.MainVerticle -conf conf.json"
Running from IDE

To run directly from within your IDE you need to use the de.cyface.collector.Application class, which is a subclass of the Vert.x launcher. Just specify it as the main class in your launch configuration with the program argument run de.cyface.collector.verticle.MainVerticle.

Mongo Database


The following is not strictly necessary but advised if you run in production or if you encounter strange problems related to data persistence. Consider reading the Mongo Database Administration Guide and follow the advice mentioned there.


To load files from the Mongo GridFS file storage use the Mongofiles tool.

  • Showing files: mongofiles --port 27019 -d cyface-data list

  • Downloading files: mongofiles --port 27019 -d cyface-data get f5823cbc-b8f5-4c80-a4b1-7bf28a3c7944

  • Unzipping files: printf "\x78\x9c" | cat - f5823cbc-b8f5-4c80-a4b1-7bf28a3c7944 | zlib-flate -uncompress > test2



Model classes shared between multiple projects.


Vert.X classes shared between multiple projects.

Release a new Version

To release a new version:

  1. Create a new release branch following the format release-x.y.z.

    1. x.y.z is the number of the new version following Semantic Versioning.

    2. Hotfixes could be branched from the already existing release-branch

      1. Merge the hotfix into the main and release branch, create pull requests and pass reviewing.

      2. No new features are allowed on a release-branch, only fixes and minor changes.

  2. Increase version numbers in root build.gradle,

    1. and optional in any associated docker-compose.yml or OpenAPI documentation (usually located in src/main/resources/webroot/openapi.yml).

    2. If you need to version sub-projects differently, create a version attribute in the corresponding build.gradle.

  3. Commit version bump and push branch to GitHub.

    1. Wait until the continuous integration system passes.

    2. Create Pull Requests from your release-x.y.z branch to release and main.

    3. Get those Pull Requests accepted and merge them to both branches

  4. Tag the new release on the release branch.

    1. Ensure you are on the correct branch and commit.

    2. Follow the guidelines from "Keep a Changelog" in your tag description.

  5. Push the release tag to GitHub.

    1. The docker image and GitHub packages are automatically published when a new version is tagged and pushed by our GitHub Actions to the GitHub Registry.

  6. Mark the released version as 'new Release' on GitHub.

Publishing artifacts to GitHub Packages manually

The artifacts produced by this project are distributed via GitHubPackages. Before you can publish artifacts you need to rename to and enter your GitHub credentials. How to obtain these credentials is described here.

To publish a new version of an artifact you need to:

  1. Increase the version number of the sub-project within the build.gradle file

  2. Call ./gradlew publish

This will upload a new artifact to GitHub packages with the new version. The artifact will be minified, optimized and obfuscated using Proguard. You need to always increase the version of the new artifact. GitHub Packages will not accept to overwrite an existing version or to upload a lower version. This project uses semantic versioning.

To Do

  • Setup Cluster

  • Vertx

  • MongoDb


Copyright 2018-2021 Cyface GmbH

This file is part of the Cyface Data Collector.

The Cyface Data Collector is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The Cyface Data Collector is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the Cyface Data Collector. If not, see