This documentation is based on the arc42 template. The examples provided there and in "DokChess als Beispiel für arc42" act as templates for some sections. Many thanks to all contributors for your valuable work.
Commuters using the Deutsche Bahn frequently face train delays and cancellations. Knowing the expected train delay or cancellation upfront allows to find alternative means of transportation so that the commuters reach their destination relaxed and on time.
The Train Delays system provides an easy mechanism to see train delays or cancellations early.
The Product Vision shows the long term goal for Train Delays.
At the moment, there is only one central functional requirement:
F1 |
Show expected next departure |
The Train Delays application shows the expected departure time of the next train leaving the station Rösrath-Stümpen. |
The following table shows the quality goals of Train Delays. The order of the goals represents their priority roughly.
Low effort maintenance (Testability) |
The risk that contributions break the system shall be low. In addition, it shall be easy for the maintainers to upgrade dependencies without breaking the system. |
Low-cost operation (Resource Utilization) |
Installing and running the system shall be very cheap. This allows the maintainers to provide the service for free while not having to pay too much for operations. |
Easy to use (Learnability) |
Users shall quickly be able to use the features of the system without error. |
Easy for contributors to contribute (Modifiability) |
It shall be easy for GitHub users to propose changes in form of pull requests. |
The following constraints apply for the Train Delays system:
| Constraint | Description and Background |
|---|---|
Open source license |
All parts of the system shall satisfy an open source license. The reason behind this is, that the system shall invite contributors. In addition, the code and concepts shall act as learning reference for the public. |
Common technologies |
The technologies used shall be widely known. This ensures that many other developers can understand the system. It also reduces the risk of complicated dependency updates and thereby simplifies maintenance. |
| Entity | Description |
|---|---|
User |
The user is the commuter who wants to see the expected train delay or cancellation. |
Deutsche Bahn Germany Open API Portal |
This API portal is operated by Deutsche Bahn Germany. It provides the timetable data used by Train Delays. |
| Entity | Description |
|---|---|
Web Browser |
The user opens the Train Delays application in the browser which retrieves the displayed page from the Train Delays system. |
Deutsche Bahn Germany Open API Portal |
Train Delays calls the APIs of the Deutsche Bahn Germany Open API Portal. |
Section Subscribe to the DB API Marketplace Timetables API describes how to register for the API and subscribe to the used services.
The following links give detailed information on the API:
-
DB API Marketplace of Deutsche Bahn, Germany
The following table relates the quality goals introduced in 1.2 Quality Goals:
| Quality Goal | Architectural Approach Supporting the Goal |
|---|---|
Low effort maintenance (Testability) |
|
Low-cost operation (Resource Utilization) |
|
Easy to use (Learnability) |
|
Easy for contributors to contribute (Modifiability) |
|
The Train Delays application is a Spring Boot REST service. The structure is simple and can be found in the folder src/main/java/systems.boos.traindelays.
| Element | Description |
|---|---|
Train Delays Docker Container |
The Train Delays web application is a Java process running inside a docker container. |
Cloud Run |
The Train Delays Docker Container is hosted in the Google Cloud Run infrastructure. |
Docker Image |
This docker image is instantiated by Cloud Run when the Train Delays Docker Container is deployed. The image is
automatically updated by Google Cloud Build whenever source code is pushed to the GitHub Repository
|
Docker Repository |
Google Cloud Run requires Docker images to be stored in a Docker Repository, which is part of the same Google project. |
Artifact Repository |
The Artifact Repository is the parent structure required when creating a Docker Repository in the Google Cloud. |
Train Delays Project |
This Google Cloud Console project is the container for all Google Cloud related configuration of the Train Delays system. |
Source Code Repository |
This repository contains the Java source code of the Train Delays web application. |
Docker Image |
This Docker image is built from the same sources as the image stored in the Docker Repository on Google. Hosting the image on dockerhub allows to share it with the Open Source Community. |
Docker Repository |
This public repository allows to share Docker images with the Open Source Community. |
This section lists the steps to set up a deployment to Google Cloud Run from scratch. This is useful in the following scenarios:
-
A new contributor has forked the Train Delays system and wants to deploy a system of her own.
-
The Train Delays system has been destroyed without being able to recover.
The train-delays web application requires an access key for the DB API Marketplace. You can get one for
free:
-
Follow the instructions in So startest Du einfach mit den APIs (in German)
-
From the Catalog of the DB API Marketplace subscribe to the Timetables API. Note: Specifying an OAuth2 Redirect URL is not necessary.
|
Warning
|
Store the Client Secret (the API Key) and the Client ID for APIs you subscribe to a password safe. The DB API Marketplace will not show the key later, but you can verify whether you have stored the correct key in DB API Marketplace / Applications. |
-
Register with Google Cloud Console
-
Authenticate with gcloud (this is a part of the previous step)
```shell gcloud init ```
-
Follow the instructions in Store Docker container images in Artifact Registry to
-
create a project with billing enabled
-
enable the Artifact Registry API in your project.
-
-
Create a service to automatically build the project by following Deploy a container to Cloud Run
-
When creating the service, connect to the (forked) GitHub repository
-
Create an environment variable named
API_KEYand copy the DB API Client Secret into it -
Create an environment variable named
CLIENT_IDand copy the DB API Client ID into it
-
|
Note
|
You can review the applications registered with your DB API Marketplace account in DB API Marketplace / Applications. |
For every change pushed to the GitHub repository, two build actions are triggered:
-
The GitHub Build and Publish action builds and runs all tests. If successful, it updates the train-delays image on dockerhub.
-
The Google Cloud Build action builds the docker image (again) and pushes it to the Docker repository within the Google project. From there, Cloud Run re-deploys the updated train delays instance.
Features and scenarios are specified using the Gherkin DSL and executed with Cucumber.
The following articles describe the used concepts:
-
Moisés Macero: Cucumber Tests in Spring Boot with Dependency Injection
-
baeldung: Asserting Log Messages With JUnit
This application uses Pact tests to verify the following APIs:
-
Consuming the Deutsche Bahn Timetables API
-
Providing the TrainDelays API
Spring UI controllers are tested using HtmlUnit. In such tests, the backend services are stubbed using Spring `MockBean`s, so that only the UI controller is tested.
The HomeControllerTest.java gives an example.
JUnit5 based unit tests verify implementation details and most error scenarios.
-
Philip Riecks: [Guide to @SpringBootTest for Spring Boot Integration Tests](https://rieckpil.de/guide-to-springboottest-for-spring-boot-integration-tests/)
The production system logs are collected by Google Cloud Run and can be viewed in the Google Cloud Console.
For the current train-delays instance, the logs can be viewed at Google Cloud Run - Logs.
If you have created your own instance, then perform the following steps to view the logs:
-
Open the Google Cloud Console
-
Select the project in the dropdown at the top of the page
-
Select the service
-
Click on the "Logs" tab
Architecture Decisions are documented in this section in the form of Architecture Decision Records (ADR). For more information, refer to the ADR GitHub Organization.
status |
accepted |
date |
July 3, 2022 |
The Train Delays web application shall be available as a permanent service with a fixed internet address.
Which deployment technology and hosting provider shall be selected?
From section 1.2 Quality Goals, especially the following quality attributes are important:
-
Low-cost operation (resource utilization)
-
Easy to use (learnability)
As described in section 2 Constraints, common technologies shall be used.
A short search on the internet brought up Geekflare: 10 Best Docker Hosting Platforms for your Containers dated June 30, 2022.
From the list, Google Cloud Run has been tested shortly and selected. Other products have not been tested yet. This ADR shall be re-evaluated when the Google Cloud Run platform shows disadvantages or when other platforms seem to fit better.
The following properties of Google Cloud Run are matching the decision drivers:
-
Common technologies
-
The platform is compatible with the currently widely spread Docker container technology
-
An automatic deployment can be triggered by pushing changes to a GitHub repository
-
-
Low-cost operation (resource utilization)
-
Container instances are only paid when they are running
-
Docker containers are only created when there are pending requests
-
Docker containers are automatically shut down when idle
-
Request rate limits can be configured
-
The maximum number of running Docker containers can be configured
-
-
Easy to use (learnability)
-
There are sufficient user guides and examples helping new user to learn the technology (see section Documentation of the Google Cloud Run Platform below)
-
The following links are presented in suggested reading order:
The following links show the tools provided by Google:
-
Google Cloud Console - Dashboard.