Home

Awesome

@azure/ng-deploy

npm version Build Status The MIT License

Deploy Angular apps to Azure using the Angular CLI

@azure/ng-deploy helps you deploy your Angular app to Azure Static Hosting using the Angular CLI.

Quick-start <a name="quickstart"></a>

  1. Install the Angular CLI and create a new Angular project.

    npm install -g @angular/cli
ng new hello-world --defaults
cd hello-world

  2. Add ng-deploy to your project and create your Azure blob storage resources.

    ng add @azure/ng-deploy

  3. You may be prompted you to sign in to Azure, providing a link to open in your browser and a code to paste in the login page.

  4. Deploy your project to Azure.

    ng run hello-world:deploy

    The project will be built with the production configuration (like running ng build -c=production).

You will see output similar to the following. Browse to the link and view your site running in Azure blob storage!

see your deployed site at https://helloworldstatic52.z22.web.core.windows.net/

Requirements

You will need the Angular CLI, an Angular project, and an Azure Subscription to deploy to Azure. Details of these requirements are in this section.

Azure

If you don't have an Azure subscription, create your Azure free account from this link.

Angular CLI <a name="angular-cli"></a>

  1. Install the Angular CLI.

    npm install -g @angular/cli

  2. Run ng --version, make sure you have angular CLI version v14 or greater.

  3. If need instructions to update the CLI, follow these upgrade instructions.

  4. Update your project using the command:

    ng update @angular/cli @angular/core

An Angular App Created by the Angular CLI

You will need an Angular app created and managed by the Angular CLI. For help getting started with a new Angular app, check out the Angular CLI.

A simple app can be created with ng new hello-world --defaults

Verify you have TypeScript version 3.4.5 or greater in your package.json file of your angular project

Details of ng-azure-deploy

How to add and configure @azure/ng-deploy <a name="ng-add"></a>

Add @azure/ng-deploy to your project by running:

ng add @azure/ng-deploy

This command will install the package to your project.

Once done, it will prompt you to sign in to Azure, providing a link to open in your browser and a code to paste in the login page.

After you sign in, it will create the needed resources in your Azure account (resource group and storage account) and configure them for static hosting. To manually configure the resources that will be used, refer to [additional options](#additional options).

Note: If you have several Azure subscriptions you will be asked to choose one.

The command will create the file azure.json with the deployment configuration and modify angular.json with the deploy commands.

Note: at the moment, the command will fail if an azure.json file already exists. Please remove the file before running the command.

deploy <a name="deploy"></a>

You can deploy your application to the selected storage account by running the following command.

ng deploy

By default, the project will be built with the production option (similar to running ng build -c=production). The files will be taken from the path configured in the build command in angular.json.

Follow these instructions if you want to set up a different path and/or build target.

You may be asked to sign in to Azure again. Then, the project will be deployed to the storage account specified in azure.json. The link to the deployed app will be presented.

Logging out from Azure <a name="logout"></a>

To clear the cached credentials run:

ng run <project-name>:azureLogout

This command is available only after signing in to Azure.

Data/Telemetry <a name="telemetry"></a>

This project collects usage data and sends it to Microsoft to help improve our products and services.

Read Microsoft's privacy statement to learn more.

To turn off telemetry, add the telemetry flag (--telemetry or -t) with the false value when running ng add, like this:

ng add ng-deploy-azure --telemetry=false

or

ng add ng-deploy-azure -t=false

Additional options <a name="options"></a>

Manual configurations <a name="manual"></a>

To manually select and/or create the resources needed for deployment, use the --manual (or -m) option:

ng add @azure/ng-deploy --manual

You will be prompted to select or create the resource group and the storage account in which the app will be deployed. If you choose to create a resource group you will be asked to select the geographical location.

Passing configuration options <a name="config"></a>

You can pass the names of the resources you'd like to use when running the command. Resources that don't already exist will be created. If using --manual you will be prompted to select the remaining configuration options. Otherwise, defaults will be used.

The available options are:

Example:

ng add @azure/ng-deploy -m -l="East US" -a=myangularapp

Name validation <a name="name-validation"></a>

When creating a new storage account, the provided name will be validated.

The requirements for these names are:

If the validation fails, the tool will suggest a valid name. You will be able to select it or try another one.

Changing the build target <a name="build-target"></a>

By default, the project is built using the build target with the production configuration, as configured in angular.json.

You can change this by editing the target and/or configuration in azure.json (after completing @azure/ng-add). Change it to a target that exists for the project in angular.json and optionally with one of its configurations. Make sure the target specifies an outputPath.

For example, if one of the targets under projects.hello-world.architect in angular.json is special-build with an optional configuration named staging, you can specify it as the target this way:

// azure.json
{
  "hosting": [
    {
      "app": {
        "project": "hello-world",
        "target": "special-build",
        "configuration": "staging"
      },
      "azureHosting": {
        ...
      }
    }
  ]
}

Another option is to skip build, and deploy directly from a specific location. To do this, delete the target and configuration from azure.json, and provide a path with a value relative to the root of the project.

For example, if the files you with to deploy exist in public/static/hello-world, change the configuration this way:

// azure.json
{
  "hosting": [
    {
      "app": {
        "project": "hello-world",
        "path": "public/static/hello-world"
      },
      "azureHosting": {
        ...
      }
    }
  ]
}

In the future we'll add an option to change this through the command line.

Continuous Integration Mode <a name="ci"></a>

When deploying from a CI environment, we switch to a non-interactive login process that requires you to provide Service Principal credentials as environment variables. A Service Principal is an application within Azure Active Directory that we can use to perform unattended resource and service level operations.

Creating a Service Principal <a name="sp"></a>

In order to create and get the Service Principal application credentials, you can either use the Azure Portal or use the Azure CLI.

We recommend using the Azure CLI and running the following command:

AZURE_SUBSCRIPTION_ID="<a valid subscription ID>"
SP_NAME='<a principal service name>'
az ad sp create-for-rbac --role="Contributor" --scopes="/subscriptions/$AZURE_SUBSCRIPTION_ID" --name="$SP_NAME"

This command will output the following values:

{
  "appId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "displayName": "<the principal service name>",
  "name": "http://<the principal service name>",
  "password": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "tenant": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

You can use the Azure CLI to test that these values work and you can log in:

az login --service-principal -u $CLIENT_ID -p $CLIENT_SECRET --tenant $TENANT_ID

Configuring the environment variables

We will need to set the following environment variables BEFORE adding @azure/ng-deploy or running the deploy command:

Here is a simple shell example:

export CI=1
export CLIENT_ID='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
export CLIENT_SECRET='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
export TENANT_ID='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
export AZURE_SUBSCRIPTION_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
ng run <project-name>:deploy

For security reasons, we highly recommend to create and provide these environment variables through a different method, eg. Github Secrets or Azure DevOps Secrets.

Reporting Security Issues <a name="issues"></a>

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) at secure@microsoft.com. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.

Contributing

Please refer to CONTRIBUTING for CLA guidance.

Thank You

Related Resources