Skip to content
This repository was archived by the owner on Jun 17, 2024. It is now read-only.

README.md

Latest commit

 

History

History
364 lines (231 loc) · 12.2 KB

README.md

File metadata and controls

364 lines (231 loc) · 12.2 KB

The Urlist - Backend

License

The backend for this project is built as a .Net Core API using .NET Core. All the data is stored in a Cosmos DB collection using the SQL API.

Table Of Contents

Configure app settings

Copy the contents of the appsettings.sample.json into the appsettings.Development.json file:

# Navigate to the project directory
cd api/src/LinkyLink

# Copy sample app settings
cp appsettings.sample.json appsettings.Development.json

Setup Database

Update the appsettings.Development.json file with your Cosmos DB Uri and Primary Key in the ServiceEndpoint & AuthKey settings respectively.

You can find the the value for ServiceEndpoint & AuthKey from the Cosmos DB resource in Azure portal or from Azure DevOps variable group (Pipelines -> Library -> Variable groups).

Cosmos DB database and container has already been created as part of deploying cosmos db resource in the global resource group

Setup Azure AD B2C Configuration

This application requires Azure Active Directory B2C for authentication/authorization. Each API request performs JWT validation from your Azure B2C tenant.

Update appsettings.Development.json file with your tenants configuration:

"AzureAdB2C": {
  "Instance": "https://[YourTenantName].b2clogin.com/tfp/",
  "ClientId": "[The Azure B2C application client ID]",
  "Name": "[YourTenantName]",
  "Domain": "[YourTenantName].onmicrosoft.com",
  "SignUpSignInPolicyId": "[Your Azure B2C policy name]"
},

Build and run locally

If you prefer to use Docker, we have provided setup instructions below

Get the prerequisites

Optional

Run from your favorite terminal

Set the ASPNETCORE_ENVIRONMENT environment variable. To

export ASPNETCORE_ENVIRONMENT=Development

Navigate into backend folder

cd /api/src/LinkyLink

Build the project

dotnet build

Start the API via the command line

dotnet run

If you receive SSL errors in your browser review the Troubleshooting local development certificate issues section

func start

Alternatively, start a debugging session in Visual Studio or Visual Studio Code.

To debug from VS Code ensure you are opening the project folder @ ./api/

Run from Visual Studio

From Visual studio choose the startup project as LinkyLink. Then from the debug start menu choose one of the following:

IIS Express

VS will start the Rest API from an IIS Express instance on a random port.

LinkLink

Will start the Rest API from a console app on port 5001 similar to calling dotnet run from your your terminal.

Using the API

To test out the API locally you can use your favorite tooling or try out some of our favorites.

Note: Change the vanityUrl value to a unique name before running Save Bundle and use the same vanityUrl name to run Get bundle for vanity url.

  • Run Save Bundle to add some data to Cosmos DB. The structure (collection, documents, etc.) in the database will be created for you if it does not exist yet.
  • Next run Get bundle for vanity url to retrieve the entry you just created.

Try out the API with Postman

View Postman setup

  • Start up Postman and import the theurlist_collection.json file that's in the api folder

  • Next import the theurlist_localhost_env.json file. That includes the Localhost environment settings.

  • Set your environment to Localhost

  • Turn off Postman SSL Verification

    postman

    postman

If everything was setup correctly, you should see a response that resembles the following.

postman

Try out the API using the REST Client extension

View REST Client setup

  • Open the validate-api.http file located in the openhack-production/api directory

  • Follow the instructions in the Run the ASP.Net Core Web API backend section of this README to start the backend

  • Select Send Request for any of the endpoints

    REST Client

Try out the API using the Swagger UI

View Swagger setup

Swagger API Documentation

  • The API uses Swagger for API Documentation. You can view the swagger documentation by navigating to: https://localhost:<port>/swagger

    swagger

Misc. Notes

  • Swagger XML Comments have been enabled to provide better API Documentation. This means that warnings will be generated for public undocumented public types and members. By default, this project disables warnings. Documentation to enable warnings can be found here

Testing

Running unit tests

Unit tests validate the individual components of the API

dotnet test api/tests/LinkyLink.Tests/LinkyLink.Tests.csproj

Running Integration tests

Integration tests validate the APIs against a running system.

The integration tests require a special configuration that uses a resource owner password credentials (ROPC) flow in Azure AD B2C. The ROPC client application only works with local user accounts. Social logins are not supported.

Configuration

Before running integration tests you must update the settings within the appsettings.json of the integration test project or set environment variables.

Appsettings

Copy the contents of the appsettings.sample.json into the appsettings.json file and fill in the missing values.

# Navigate to the test directory
cd api/tests/LinkyLink.Integration.Tests

# Copy sample .env settings
cp appsettings.sample.json appsettings.json

# FILL IN THE missing values
Environment Variables
# The host address of the deployed environment (dev/staging/prod) to test
export INTTEST_BaseAddress=
# The client ID of your test application within Azure B2C
export INTTEST_AzureAdB2C__ClientId=
# The Azure B2C authority endpoint
export INTTEST_AzureAdB2C__Authority=
# The scope to set on your access token
export INTTEST_AzureAdB2C__Scope=
# The username of your test user account
export INTTEST_AzureAdB2C__Username=
# The password of your test user account
export INTTEST_AzureAdB2C__Password=

Run tests with .Net CLI

cd ../../../
dotnet test api/tests/LinkyLink.Integration.Tests/LinkyLink.Integration.Tests.csproj

Docker local development

This is an alternative local development option. The container sets the ASPNETCORE environment to Development, so make sure you have a appsettings.Development.json created and configured before building the container image.

Setup certificate for HTTPS

By default, https is not set up for container. In essence, you need to mount a drive containing your development certificate into the container.

We have provided sample commands below to set up https.

For more details, see this doc on Hosting ASP.NET Core images with Docker over HTTPS

Usage

Without HTTPS

docker build -t linkylink .
docker run -p 5000:80 -it linkylink
curl http://localhost:5000/api/links/postman-test

With HTTPS

Here's a sample script for running on MacOS. For other OS, you'll have to make some modifications by following this guide

Expand to see commands 
# remove existing certificate
dotnet dev-certs https --clean

# generate cert - the password use here must match the one provided below
dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p "password"

# trust cert
dotnet dev-certs https --trust

# build image
docker build -t linkylink .

# run contaienr
docker run --rm -it \
  --name api \
  -p 5000:80 -p 5001:443 \
  -e ASPNETCORE_URLS="https://+;http://+" \
  -e ASPNETCORE_HTTPS_PORT=5001 \
  -e ASPNETCORE_Kestrel__Certificates__Default__Password="password" \
  -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx \
  -v ${HOME}/.aspnet/https:/https/ \
  linkylink

curl http://localhost:5000/api/links/postman-test

Troubleshooting local development certificate issues

By default the application runs under HTTPS. If you have not previously trusted a .NET Core localhost development certificate you will need to generate and trust your a local development certificate otherwise you will receive warnings from your browser.

For detailed instructions you can review the Troubleshooting Guide or follow the steps below.

Windows & MacOS

In Windows and MacOS the process is straight forward and you can run a single command.

Generates and trust the self signed local development certificate

# Generate and trust development certificate
dotnet dev-certs https --trust

Windows with WSL

If you are running the Windows Subsystem for Linux (WSL) you have a little more work to do:

Export existing certificate

Generate and export the certificate created within WSL.

# Run from your Windows HOST OS setting your own password for the certificate
dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnet.pfx -p <PASSWORD>

Install Certificate into your Trust Root Certificates Store

Install the certificate with the command below. When prompted enter the password you used in the previous step

# Run from your Windows HOST OS in an elevated command prompt
certutil -importPFX "Root" "%USERPROFILE%\.aspnet\https\aspnet.pfx"

You will be required to run this command from an elevated command prompt

Set environment variables for .NET Core runtime

Tell the .NET Core runtime what certificate to use. User the same password you created in the previous steps and point to the location on your windows host where the certificate was exported to.

# Run from your WSL Terminal
export ASPNETCORE_Kestrel__Certificates__Default__Password=<PASSWORD>
export ASPNETCORE_Kestrel__Certificates__Default__Path=/mnt/c/Users/<USERNAME>/.aspnet/https/aspnet.pfx

These environment variables will only be available in your current terminal session.
To set them globally add them to your WSL ~/.bashrc file You may need to close all tabs and restart your browser for the certificate changes to take effect