Coding in Coral

Overview

Coral is split into several repositories. It has libraries and services written in .NET Core and the frontend code written in typescript/react.

Repositories for libraries and services

Coral Shared

This repository contains the pieces that are shared between v1 of Coral and the external and internal vendors. All cross-cutting concerns that are specific to Coral should go in here. The client access parts will eventually be moved out as v1 subsides in adoption. Unless you are doing cross-cutting things and not extending the vendors using the service access parts, you should not have to make changes here.

Official Build Status Public Release

Coral Framework

This repository contains the libraries you must depend on when writing or extending vendors. So unless you are extending the core of Coral or fixing a core bug, you should not need to make changes in this repository.

Official Build Status Public Release

Coral Internal

This repository contains all the code that cannot be exposed outside of Microsoft. It holds the Legacy v1 API and the vendors that integrate with services that are not exposed publicly. So unless you need a fix in the legacy API or you need to integrate with an internal system @Microsoft, you should not need to make changes here.

Official Build Status Public Release

Coral

This is the main repository and contains all services that we deploy and the vendors that integrate with publicly exposed services.

Official Build Status PROD Release status

Repositories for frontend

Coral Azure DevOps Extension

This is the main integration with Azure DevOps and currently serves as the user experience for Coral

Official Build status PROD Release status

Coral Documentation Experience

This repository contains the user experience code that expose these pages. It is basically pulling markdown files that are statically built for each version of the coral service.

Official Build Status Public Release

Common prerequisites

For developing Coral locally the prerequisites are

Building locally

Building services and libraries

There are two options for most of our pipelines: Either maintain the dotnet runtime locally or use the vscode dev container support.

The steps to get started if you have the runtime locally is:

Clone the repository git clone <clone url> and change directory to it, then restore the packages using dotnet restore --interactive and finally build everything with dotnet build (You may supply dirs.proj to these commands)

Building frontend

The frontend code can be built simply by doing npm install and npm start. This will recompile every time you save a file.

Unit-tests

Once you have a successful local build you should ensure that unit-tests are passing.

Unit-tests for services and libraries

Running dotnet test will execute all tests in the repository.

Unit-tests for frontend

There are currently no unit-test coverage for the frontend code.

Local integration testing

Setting up local dependencies

Before merging a change to master, we validate it locally. We use docker-compose to manage the external dependencies. Not all dependencies have docker images and for those we have fake implementations. The ones that docker-compose.yml describe are:

  • MailHog for local SMTP support
  • MongoDB for the CosmosDB vendor storage
  • Gremlin for the CosmosDB graph storage

So to make docker host the local services run docker-compose up -d

Starting Coral services locally

In Coral there are currently three services: The Frontend API service, the Silo service and the Documentation API service. The two API services depend on the Silo service for all vendor access, so in most cases you need to start the API service that you want to test along with the Silo.

In Visual Studio this can be managed using startup projects and in Visual Studio Code we have launch settings defined. So select the startup/launcher you need and press F5 which will take you to debug mode. Follow the links to learn more about how to debug using Visual Studio or Visual Studio Code.

At this point you should be able to use swagger or any other ReST client to access the APIs

Testing with the user experiences

For the user experiences we use Visual Studio Code and the shared flow is to first npm start from within the experience repository folder and then load a browser to the endpoint.

Special steps for the Azure DevOps Extension

Getting the pre-production and local extension

The extension requires an actual Azure DevOps instance to load in the iframe. Therefore, to hit services running locally on your computer, you need a special extension installed on the Azure DevOps instance. This extension requires a qualified domain name.

  1. Get the extensions installed on your Azure DevOps test account. Click this link and send the email to coralonboarding@microsoft.com stating your Azure DevOps account/url. We will share the extensions with your account and get back to you.
  2. Edit the hosts file (/etc/hosts on Linux/MacOS or c:\Windows\System32\Drivers\etc\hosts on Windows) and append a line 127.0.0.1 coral.local
  3. After npm start load https://coral.local:8889 in a browser and accept the invalid certificate.
  4. Once the extensions are installed you can navigate to https://dev.azure.com/<account>/<project>/_apps/hub/fastagility.coral-ui.coral. Replace ‘<account>' and ‘<project>' with the correct values.

Code review

Initiate a Azure DevOps GIT Pull Request