cwa-server

Corona-Warn-App Server

Development • Service APIs • Documentation • Support • Contribute • Contributors • Repositories • Licensing

The goal of this project is to develop the official Corona-Warn-App for Germany based on the exposure notification API from [Apple](https://www.apple.com/covid19/contacttracing/) and [Google](https://www.google.com/covid19/exposurenotifications/). The apps (for both iOS and Android) use Bluetooth technology to exchange anonymous encrypted data with other mobile phones (on which the app is also installed) in the vicinity of an app user's phone. The data is stored locally on each user's device, preventing authorities or other parties from accessing or controlling the data. This repository contains the **implementation of the server for encryption keys** for the Corona-Warn-App. In this documentation, Corona-Warn-App services are also referred to as CWA services. ## Architecture Overview You can find the architecture overview [here](/docs/ARCHITECTURE.md), which will give you a good starting point in how the backend services interact with other services, and what purpose they serve. ## Development After you've checked out this repository, you can run the application in one of the following ways: * As a [Docker](https://www.docker.com/)-based deployment on your local machine. You can run either: * Single components using the respective Dockerfile or * The full backend using the Docker Compose (which is considered the most convenient way) * As a [Maven](https://maven.apache.org)-based build on your local machine. If you want to develop something in a single component, this approach is preferable. ### Docker-Based Deployment If you want to use Docker-based deployment, you need to install Docker on your local machine. For more information about downloading and installing Docker, see the [official Docker documentation](https://docs.docker.com/get-docker/). #### Running the Full CWA Backend Using Docker Compose For your convenience, a full setup for local development and testing purposes, including the generation of test data has been prepared using [Docker Compose](https://docs.docker.com/compose/reference/overview/). To build the backend services, run ```docker-compose build``` in the repository's root directory. A default configuration file can be found under ```.env``` in the root folder of the repository. If the endpoints are to be exposed to the network the default values in this file should be changed before docker-compose is run. Once the services are built, you can start the whole backend using ```docker-compose up```. The distribution service runs once and then finishes. If you want to trigger additional distribution runs, run ```docker-compose run distribution```. The docker-compose contains the following services: Service | Description | Endpoint and Default Credentials ------------------|-------------|----------- submission | The Corona-Warn-App submission service | `http://localhost:8000`
`http://localhost:8006` (for actuator endpoint) distribution | The Corona-Warn-App distribution service | NO ENDPOINT postgres | A [postgres] database installation | `localhost:8001`
`postgres:5432` (from containerized pgadmin)
Username: postgres
Password: postgres pgadmin | A [pgadmin](https://www.pgadmin.org/) installation for the postgres database | `http://localhost:8002`
Username: [email protected]
Password: password cloudserver | [Zenko CloudServer] is a S3-compliant object store | `http://localhost:8003/`
Access key: accessKey1
Secret key: verySecretKey1 verification-fake | A very simple fake implementation for the tan verification. | `http://localhost:8004/version/v1/tan/verify`
The only valid tan is `edc07f08-a1aa-11ea-bb37-0242ac130002`. ##### Known Limitation In rare cases the docker-compose runs into a timing issue if the distribution service starts before the bucket of the objectstore was created. This is not a big issue as you can simply run ```docker-compose run distribution``` to trigger additional distribution runs after the objectstore was initialized. #### Running Single CWA Services Using Docker If you would like to build and run a single CWA service, it's considered easiest to run them in a Docker environment. You can do this using the script provided in the respective CWA service directory. The Docker script first builds the CWA service and then creates an image for the runtime, which means that there are no additional dependencies for you to install. To build and run the distribution service, run the following command: ```bash ./services/distribution/build_and_run.sh ``` To build and run the submission service, run the following command: ```bash ./services/submission/build_and_run.sh ``` The submission service is available on [localhost:8080](http://localhost:8080 ). ### Maven-Based Build If you want to actively develop in one of the CWA services, the Maven-based runtime is most suitable. To prepare your machine to run the CWA project locally, we recommend that you first ensure that you've installed the following: * Minimum JDK Version 11: [OpenJDK](https://openjdk.java.net/) / [SapMachine](https://sap.github.io/SapMachine/) * [Maven 3.6](https://maven.apache.org/) * [Postgres] * [Zenko CloudServer] If you are already running a local Postgres, you need to create a database `cwa` and run the following setup scripts: * Create the different CWA roles first by executing [create-roles.sql](./setup/setup-roles.sql). * Create local database users for the specific roles by running [create-users.sql](./local-setup/create-users.sql). * It is recommended to also run [enable-test-data-docker-compose.sql](./local-setup/enable-test-data-docker-compose.sql) , which enables the test data generation profile. If you already had CWA running before and an existing `diagnosis-key` table on your database, you need to run [enable-test-data.sql](./local-setup/enable-test-data.sql) instead. You can also use `docker-compose` to start Postgres and Zenko. If you do that, you have to set the following environment-variables when running the Spring project: For the distribution module: ```bash POSTGRESQL_SERVICE_PORT=8001 VAULT_FILESIGNING_SECRET= SPRING_PROFILES_ACTIVE=signature-dev,disable-ssl-client-postgres ``` For the submission module: ```bash POSTGRESQL_SERVICE_PORT=8001 SPRING_PROFILES_ACTIVE=disable-ssl-client-postgres ``` #### Configure After you made sure that the specified dependencies are running, configure them in the respective configuration files. * Configure the Postgres connection in the [submission config](./services/submission/src/main/resources/application.yaml) and in the [distribution config](./services/distribution/src/main/resources/application.yaml) * Configure the S3 compatible object storage in the [distribution config](./services/distribution/src/main/resources/application.yaml) * Configure the private key for the distribution service, the path need to be prefixed with `file:` * `VAULT_FILESIGNING_SECRET` should be the path to the private key, example available in `/docker-compose-test-secrets/private.pem` #### Build After you've checked out the repository, to build the project, run ```mvn install``` in your base directory. #### Run Navigate to the service you want to start and run the spring-boot:run target. The configured Postgres and the configured S3 compliant object storage are used as default. When you start the submission service, the endpoint is available on your local port 8080. If you want to start the submission service, for example, you start it as follows: ```bash cd services/submission/ mvn spring-boot:run ``` #### Debugging To enable the `DEBUG` log level, you can run the application using the Spring `debug` profile. ```bash mvn spring-boot:run -Dspring.profiles.active=debug ``` To be able to set breakpoints (e.g. in IntelliJ), it may be necessary to use the ```-Dspring-boot.run.fork=false``` parameter. ## Service APIs The API that is being exposed by the backend services is documented in an [OpenAPI](https://www.openapis.org/) specification. The specification files are available at the following locations: Service | OpenAPI Specification --------------------------|------------- Submission Service | [services/submission/api_v1.json](https://github.com/corona-warn-app/cwa-server/raw/HEAD/services/submission/api_v1.json) Distribution Service | [services/distribution/api_v1.json](https://github.com/corona-warn-app/cwa-server/raw/HEAD/services/distribution/api_v1.json) ## Spring Profiles ### Distribution See [Distribution Service - Spring Profiles](/docs/DISTRIBUTION.md#spring-profiles). ### Submission See [Submission Service - Spring Profiles](/docs/SUBMISSION.md#spring-profiles). ## Documentation The full documentation for the Corona-Warn-App can be found in the [cwa-documentation](https://github.com/corona-warn-app/cwa-documentation) repository. The documentation repository contains technical documents, architecture information, and whitepapers related to this implementation. The documentation for cwa-server can be found under the [/docs](./docs) folder. The JavaDoc documentation for cwa-server is hosted by Github Pages at [https://corona-warn-app.github.io/cwa-server](https://corona-warn-app.github.io/cwa-server). ## Support and Feedback The following channels are available for discussions, feedback, and support requests: | Type | Channel | | ------------------------ | ------------------------------------------------------ | | **General Discussion** | | | **Concept Feedback** | | | **Backend Issue** | | | **Other Requests** | | ## How to Contribute Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](./CONTRIBUTING.md). By participating in this project, you agree to abide by its [Code of Conduct](./CODE_OF_CONDUCT.md) at all times. ## Contributors The German government has asked SAP and Deutsc