Deployment quickstart

Prerequisites

The CovidSafe Backend has been tested for deployment in a Microsoft Azure environment. Being an ASP.NET Core Web API, it should be deployable in any IIS environment as long as the environment variables are set properly.

These instructions assume you are running Visual Studio 2019 or later and are generally familiar with creating resources using the Azure Portal; earlier versions of Visual Studio could work, but have not been tested. The Azure documentation site may be helpful for getting started.

Given the potential scale of any contact tracing operation it is imperative any host operating one of these services has a decent understanding of how to manage the underlying infrastructure.

Stack

At minimum, the following resources are required to host:

• Azure App Service
  • .NET Core 2.1 (LTS) Runtime stack
• Azure CosmosDB
  • Core (SQL) API
  • Use /partitionKey as the Partition Key when creating a container.

Environment variables

• ApplicationInsights:InstrumentationKey (optional)
  • Key used to identify the application, if using Application Insights.
• CosmosSchema:DatabaseName
  • Name of the CosmosDB database used for CovidSafe data storage.
  • Ex: messages
• CosmosSchema:MaxDataAgeToReturnDays
  • Maximum age of data to return, in days. When querying data for a region, any database objects older than this value are ignored; this prevents old trace data which may no longer be relevant from getting returned to users.
  • Ex: 14
• CosmosSchema:MessageContainerName
  • Name of the actual Cosmos container (within the database specified previously) which stores message objects.
  • Ex: messages_api_2020_04_15
• DefaultApiVersion
  • Sets the version of the API used when a request does not specify in a query parameter.
  • Ex: 2020-04-15
• KeyVaultUrl (optional)
  • URL to the Azure Key Vault used by the web service, if desired.
  • This is strongly recommended for production environments. The current implementation uses Managed Service Identity (MSI) to avoid managing connection strings. See this article for information on enabling an Identity for your App Service. Ensure your Microsoft Account also has an Access Policy to enable Get and List permissions so you can use it when debugging locally.
  • Ex: https://myvaultname.vault.azure.net/
• SwaggerHosts
  • Semi-colon (;) delimited string of hosts
  • Ex: https://myapi.local/

The included appsettings.json file under the CovidSafe.API project provides a sample configuration for getting a local copy of the code running, though some values may need adjusting.

Connection Strings

• CosmosConnection
  • Connection string used to access the Azure CosmosDB instance. This can be specified in a few ways:
    • Via an Azure Key Vault.
    • Via the Connection Strings section of the Azure Portal.
    • Via appsettings.json (for local environments).
      • If you use this option, be mindful: do NOT check the file into source control or you will have shared application secrets in a repository!
  • Ex: AccountEndpoint={hostUrl};AccountKey={cosmosKey}

Running the CovidSafe Backend

1. Deploy the services listed above to the target Azure subscription. While Visual Studio can help users create an App Service directly, services like Azure CosmosDB must already be created to host a local development environment.
2. Clone this repository and open CovidSafe.sln in Visual Studio.
3. Under CovidSafe.API, open appsettings.json.
4. Using the above section on Environment variables, fill in or replace any values with those for the target hosting environment.
5. In the Visual Studio UI, click 'IIS Express' or press F5 to start the debugger.

Upon successful compilation, the system default web browser will launch and navigate to https://localhost:44347/swagger. If the Swagger documentation appears, it is a good sign the service is operating correctly.

Deployment to Azure

Assuming the necessary resources have been deployed to the target Azure Subscription, deployment is as simple as right-clicking CovidSafe.API in Visual Studio and clicking 'Publish...'.

Select the correct Subscription, Resource Group, and App Service slot to deploy.