Skip to content
This repository has been archived by the owner on Aug 5, 2024. It is now read-only.

Latest commit

 

History

History
118 lines (71 loc) · 6.54 KB

quickstart.md

File metadata and controls

118 lines (71 loc) · 6.54 KB
Raw

Quickstart

In this guide you will learn how to:

  • Set up your repo and getting up and running in GitHub Codespaces.
  • Connect the repo to Azure and deploy your application.
  • View the live app's logs and metrics in the Azure Portal.

Open your repo in Codespaces

Codespaces is a Github feature that enables you to run a full development environment in the cloud. It uses VS Code in the browser to host dev containers. The template comes complete with all the necessary tools and extensions for developing your application.

Note: You can also run the template locally, by cloning the repo.

These steps will help you create your own repository and open it in Codespaces:

  1. Click the green button Use this template to create a copy of this repository.

  2. Change the Owner to your GitHub account and enter a unique repository name.

  3. Click Create repository from template.

  4. Ensure you are in the newly create repository when continuing this quickstart.

  5. Click on the green Code button and select Open with Codespaces.

    Open with Codespaces

    Note: This feature is in private preview, so if you do not see the option, learn how to run your app in a dev container.

  6. Create a new Codespace if one does not already exist.

    Create new Codespace

  7. The repo will open inside of VS Code in your browser.

Run the app

  1. Once Codespaces is open, hit F5 to start the application. This will run the Debug webAPI launch task.

    Debug Web API Task

  2. When VS Code prompts you, select Open in Browser in the lower right. This will take you to the Swagger page exposed by the Web API where you can test the different routes.

    Note If your browser is blocking the pop-up, you'll have to restart the debug task with Ctrl+Shift+F5.

Deploy the app

The template sets up your deployment process by implementing GitHub workflows to deploy your application to Azure. More information on deployment can be found in the conceptual documentation. Now that your app is running in Codespaces, let's get it hosted in Azure!

Connect your repository to Azure

GitHub workflows will use a Service Principal to authenticate to Azure and deploy the application to your subscription.

These steps will help you create a Service Principal and hook it up to your GitHub repo.

  1. Create a new Azure subscription or use an existing one.

  2. Create a new terminal (Ctrl + Shift + `) in Codespaces.

  3. Log into your Azure account with az login and follow the prompts.

  4. List your available subscriptions with az account list and set the default by name or ID with az account set -s <subName or subID>

  5. Enter az account show to verify the correct subscription is selected.

  6. Enter az ad sp create-for-rbac --sdk-auth --role Contributor --scopes /subscriptions/{subscriptionId} to create a service principal, replacing subscriptionId with your own subscription ID.

    Note: This Service Principal will have subscription-wide contributor rights. This gives access to all resources in the subscription.

  7. Copy the full JSON output including {}.

  8. On GitHub.com, navigate to your repository and go to Settings > Secrets > New repository secret. Click here for more information on creating a GitHub secret.

    Repository Settings Button

  9. Add a new secret named AZURE_CREDENTIALS and paste the full JSON output.

Start the build workflow

The build and release workflow will build, test, and deploy the application using the configuration in config.yaml.

These steps will help you start the build workflow manually.

  1. From GitHub in the browser, select the Actions tab in your repo.
  2. Select the Build and Release workflow.
  3. Open the Run workflow dropdown and select Run workflow.

View your live app

Once your app is successfully deployed, your Web API is running in an App Service and now communicates with an instance of Azure SQL Database. Your app is live!

These steps will help you open a running instance of your application in the cloud.

  1. Once the deploy workflow is successfully completed, go to the Azure Portal and login.

  2. Click the top-middle search bar and search for Subscriptions under the Services category.

  3. Select the default subscription you chose during Connect your repository to Azure.

  4. On the left hand side navigation, scroll down and select Resource groups.

    Resource Groups

  5. Select the resource group that contains rg-{gitHub repository name}. This should be the resource group created by the template deployment.

  6. Select the App Service resource.

  7. In the Essentials section, click the URL to open your deployed application.

Manage and monitor your app

We've set up an Application Insights resource with your deployment, so you can monitor and view the logs of your app in real time.

These steps will help you view the health, logs, and metrics of your app.

  1. From the Azure Portal, navigate to your subscription and select the resource group that begins with test (directions in the previous section).

  2. Select the Application Insights resource that contains insights.

  3. From the Overview tab, observe the key diagnostics of your cloud application.

  4. Click on Application Dashboard to get a comprehensive view of your app's performance and reliability.

    Application Dashboard

Next steps

Great job, you did it! Now that your application is up and running, you may want to:

Contact us

  • Did you find a bug or think of an idea to improve this template? Submit an issue. We love your feedback!