Skip to content

Latest commit

 

History

History
119 lines (77 loc) · 8.34 KB

README.md

File metadata and controls

119 lines (77 loc) · 8.34 KB

Project Jackson API

This readme contains the Backend API, written in Java using the Spring Framework.

Quickstart

Are IDEs more your style? Skip ahead to our IDE Quickstart.

git clone https://github.com/Microsoft/containers-rest-cosmos-appservice-java.git

mvn spring-boot:run

Note: Running will use Maven to install all dependencies, and then use Java to run the application.

Quickstart with IDE

We recommend using IDEA so these steps assume the use of that IDE.

git clone https://github.com/Microsoft/containers-rest-cosmos-appservice-java.git
  • 🏗 Install Oracle JDK8u191 to help us build Java code
  • 📦 Install IntelliJ IDEA
  • 💡 Open IDEA and select "Open Project", choosing api/ from the project directory as the IDEA project location
  • ⚙️ In the bottom right, IDEA will tell you "Maven projects need to be imported" - select "Import Changes"
  • 📓 Create a Run Configuration for Maven, specifying spring-boot:run as the "Command Line" value in the "Parameters" pane
Command Line: spring-boot:run

Note: Running the application will use Maven to install all dependencies, and then use Java to run the application.

Deploying to Production

In the Quickstart section above, we covered how to run this reference solution locally. In this section, we'll discuss how to deploy the solution to Azure to simulate a scalable production environment.

When running in a production environment, there are a number of required Application Configuration values that must be defined. Please see the Application Configuration section for more information.

To deploy a production instance of this service to Azure, we recommend reading the infrastructure README.md file, which features an easy "deploy to Azure" button. We also recommend the use of a Continuous Delivery pipeline to manage scalable deployments to Azure. A walk-through is in the works.

Setting Environmental Variables in Azure Resources

To configure environmental variables in Azure Resources:

  • Open the blade for the application in the Azure Portal
  • Click on Application Settings
  • Under the Application Settings category, there are key/value pairs that your app will load on start up. Additional information provided here.

Application Configuration

We use Profiles for configuration. Currently development and production are the two possible values for the spring.profiles.active property. By default, development is assumed. Note: default is technically it's own profile, which is the same as development. The following sections document the possible configuration values as logically grouped sets.

Authentication

Note: If you're running with the development profile, this is optional.

To configure authentication, you'll need to specify your authentication provider's jwt or jwk key uri. For more information see the spring docs.

The OAUTH_KEYSET_URI environment variable must be set to that uri. For Microsoft Azure, that value can always be https://login.microsoftonline.com/common/discovery/keys - this is because a common key set is used for all Azure Active Directory applications.

The OAUTH_RES_ID environment variable should (but optionally may not be) set to the application id from the oauth2 provider. If this is omitted, the authentication layer will validate whether the token is created by the given provider, but not that it is issued for your specific application.

Learn more about how to configure an Azure Active Directory application here.

CORS

We use an environmental variable called ALLOWED_ORIGIN and set it to * in azuredeploy.json for both the person and title APIs. This will allow the frontend to talk to the backend without throwing CORS errors.

Database

Note: If you're running with the development profile, this is optional.

To configure communications with a database, the following environment variables are used:

  • DB_CONNSTR - a mongo database connection string (ex: mongodb://db.com/myDb)
  • DB_NAME - a mongo database name (ex: myDb)
  • EXCLUDE_FILTER - [optional] a (regex capable) list of classes to exclude from loading (ex: TitleRepository,PersonRepository)

Mock Data

By default, when running with the development profile, test data is auto-loaded into the embedded mongo instance. However, if you set the above environment variables, that configuration will take precedence.

This mock data contains about 8 entries from each collection, and can be found in the src/main/resources/testdata folder. There are related entries across each collection to prove out the custom API routes.

Logging

Spring uses Commons Logging under the hood, more details can be found here. To configure logging, the following environment variables can be used:

Note: These values should be a [valid log level](a valid log level)

  • logging.level.root - Configures the logging level for the whole application, including frameworks
  • logging.level.com.microsoft.cse.* - Configures the logging level for our application, excluding frameworks
  • logging.level.org.zalando.logbook - Configures the logging of HTTP requests/responses to the console. Set to TRACE
  • logging.level.org.springframework.data.mongodb.core.MongoTemplate - Configures the logging of a MongoDB query. Set to DEBUG to see how any constructed query gets data from MongoDB

To configure application insights logging, the following environment variable must be set:

Testing

To run the tests, use mvn test. This project strives to unit test each behavior, and integration test end to end scenarios.