Skip to content

tutorial-custom-container.md

Latest commit

 

History

History
960 lines (604 loc) · 49.2 KB

tutorial-custom-container.md

File metadata and controls

960 lines (604 loc) · 49.2 KB
title Tutorial: Build and Run a Custom Image in Azure App Service
description Learn how to migrate custom software to App Service in a custom container. Build a custom image and deploy it to App Service.
ms.topic tutorial
ms.date 08/27/2025
ms.author msangapu
author msangapu-msft
keywords azure app service, web app, linux, windows, docker, container
zone_pivot_groups app-service-containers-windows-linux
ms.service azure-app-service
ms.custom
devx-track-csharp
mvc
devx-track-azurecli
devdivchpfy22
linux-related-content
sfi-image-nochange

Migrate custom software to Azure App Service by using a custom container

::: zone pivot="container-windows"

Azure App Service provides predefined application stacks, like ASP.NET or Node.js, on Windows. These application stacks run on IIS. The preconfigured Windows environment locks down the operating system from:

  • Administrative access.
  • Software installations.
  • Changes to the global assembly cache.

For more information, see Operating system functionality on App Service.

You can deploy a custom-configured Windows image from Visual Studio to make OS changes that your app needs. Doing so makes it easy to migrate an on-premises app that requires a custom OS and software configuration. This tutorial demonstrates how to migrate to App Service an ASP.NET app that uses custom fonts installed in the Windows font library. You deploy a custom-configured Windows image from Visual Studio to Azure Container Registry and then run it in App Service.

:::image type="content" source="media/tutorial-custom-container/app-running-newupdate.png" alt-text="Screenshot that shows the web app running in a Windows container.":::

Prerequisites

Set up the app locally

Download the sample

In this step, you set up the local .NET project.

The sample project contains a simple ASP.NET application that uses a custom font that's installed into the Windows font library. It's not necessary to install fonts. However, the sample is an example of an app that's integrated with the underlying OS. To migrate such an app to App Service, you either rearchitect your code to remove the integration, or migrate it as-is in a custom Windows container.

Install the font

In Windows Explorer, go to custom-font-win-container-master/CustomFontSample, right-click FrederickatheGreat-Regular.ttf, and select Install.

This font is publicly available from Google Fonts.

Run the app

Open the custom-font-win-container-master/CustomFontSample.sln file in Visual Studio.

Select Ctrl+F5 to run the app without debugging. The app is displayed in your default browser.

:::image type="content" source="media/tutorial-custom-container/local-app-in-browser.png" alt-text="Screenshot showing the app displayed in the default browser.":::

Because the app uses an installed font, the app can't run in the App Service sandbox. However, you can deploy it by using a Windows container instead, because you can install the font in the Windows container.

Configure Windows container

In Solution Explorer, right-click the CustomFontSample project and select Add > Container Orchestration Support.

:::image type="content" source="media/tutorial-custom-container/enable-container-orchestration.png" alt-text="Screenshot of the CustomFontSample project in Solution Explorer. The Add and Container Orchestrator Support menu items are highlighted.":::

Select Docker Compose > OK.

Your project is now set to run in a Windows container. A Dockerfile is added to the CustomFontSample project, and a docker-compose project is added to the solution.

From Solution Explorer, open Dockerfile.

You need to use a supported parent image. Change the parent image by replacing the FROM line with the following code:

FROM mcr.microsoft.com/dotnet/framework/aspnet:4.7.2-windowsservercore-ltsc2019

Add the following line to the end of the file and save the file:

RUN ${source:-obj/Docker/publish/InstallFont.ps1}

You can find InstallFont.ps1 in the CustomFontSample project. It's a simple script that installs the font. You can find a more complex version of the script in the PowerShell Gallery.

Note

To test the Windows container locally, ensure that Docker is started on your local machine.

Publish to Azure Container Registry

Azure Container Registry can store your images for container deployments. You can configure App Service to use images that are hosted in Container Registry.

Open the Publish window

In Solution Explorer, right-click the CustomFontSample project and select Publish.

:::image type="content" source="media/tutorial-custom-container/open-publish-wizard.png" alt-text="Screenshot of the CustomFontSample project in Solution Explorer. The Publish menu item is highlighted.":::

Create and publish the registry

  1. In the Publish window, select Azure, and then select Next.

  2. Select Azure Container Registry, and then select Next.

  3. Select the subscription where you want to publish the registry, and then select Create new.

:::image type="content" source="media/tutorial-custom-container/create-registry.png" alt-text="Screenshot that shows the Publish window. The Create new button is highlighted.":::

Sign in with an Azure account

In the Azure Container Registry window, select Add an account, and then sign in to your Azure subscription. If you're already signed in, select the account containing the desired subscription from the dropdown list.

Configure the registry

Configure the new container registry by using the suggested values in the following table as a guide. When finished, select Create.

Setting Suggested value
DNS prefix Keep the generated registry name, or change it to another unique name.
Resource group Select New, enter myResourceGroup, and then select OK.
SKU Basic. For more information, see Pricing tiers.
Registry Location West Europe

:::image type="content" source="./media/tutorial-custom-container/configure-registry.png" alt-text="Screenshot of the Azure Container Registry window.":::

Select Finish.

A terminal window opens and displays the image deployment progress. Wait for the deployment to complete.

Sign in to Azure

Sign in to the Azure portal.

Create a web app

Select Create a resource, and then select Create under Web App.

Configure app basics

On the Basics tab, configure the settings by using the following table as a guide.

Setting Suggested value
Subscription Make sure the correct subscription is selected.
Resource group Select Create new, enter myResourceGroup, and then select OK.
Name Enter a unique name. The URL of the web app is https://<app-name>.azurewebsites.net, where <app-name> is your app name.
Publish Container
Operating System Windows
Region West Europe
Windows Plan Select Create new, enter myAppServicePlan, and then select OK.

Your Basics tab should look similar to this one:

:::image type="content" source="media/tutorial-custom-container/configure-app-basics.png" alt-text="Screenshot of the Basics tab that's used to configure the web app.":::

Configure the Windows container

On the Container tab, configure your custom Windows container as shown in the following table, and then select Review + create.

Setting Suggested value
Image Source Azure Container Registry
Registry Select the registry you created earlier.
Image customfontsample
Tag latest

Complete app creation

Select Create and wait for Azure to create the required resources.

Browse to the web app

When the deployment is complete, a notification message appears:

:::image type="content" source="media/tutorial-custom-container/portal-create-finished.png" alt-text="Screenshot that shows the notification message." lightbox="media/tutorial-custom-container/portal-create-finished.png":::

  1. Select Go to resource.

  2. In the app page, select the link under URL.

A new browser page is opened to the following page:

:::image type="content" source="media/tutorial-custom-container/app-starting.png" alt-text="Screentshot that shows the new browser page for the web app.":::

Wait a few minutes and try again, until you get the homepage with the font you expect:

:::image type="content" source="media/tutorial-custom-container/app-running-newupdate.png" alt-text="Screenshot of the homepage with the font you configured.":::

Congratulations! You've migrated an ASP.NET application to App Service in a Windows container.

View the container startup logs

It might take some time for the Windows container to load. To see the progress, go to the following URL. (Replace <app-name> with the name of your app.)

https://<app-name>.scm.azurewebsites.net/api/logstream

The streamed logs look like this:

14/09/2018 23:16:19.889 INFO - Site: fonts-win-container - Creating container for image: customfontsample20180914115836.azurecr.io/customfontsample:latest.
14/09/2018 23:16:19.928 INFO - Site: fonts-win-container - Create container for image: customfontsample20180914115836.azurecr.io/customfontsample:latest succeeded. Container Id 329ecfedbe370f1d99857da7352a7633366b878607994ff1334461e44e6f5418
14/09/2018 23:17:23.405 INFO - Site: fonts-win-container - Start container succeeded. Container: 329ecfedbe370f1d99857da7352a7633366b878607994ff1334461e44e6f5418
14/09/2018 23:17:28.637 INFO - Site: fonts-win-container - Container ready
14/09/2018 23:17:28.637 INFO - Site: fonts-win-container - Configuring container
14/09/2018 23:18:03.823 INFO - Site: fonts-win-container - Container ready
14/09/2018 23:18:03.823 INFO - Site: fonts-win-container - Container start-up and configuration completed successfully

::: zone-end

::: zone pivot="container-linux"

Azure App Service uses Docker container technology to host both built-in images and custom images. To see a list of built-in images, run the Azure CLI command, az webapp list-runtimes --os linux. If those images don't satisfy your needs, you can build and deploy a custom image.

Note

Your container should target the x86-64 architecture. ARM64 isn't supported.

In this tutorial, you learn how to:

[!div class="checklist"]

  • Push a custom Docker image to Azure Container Registry.
  • Deploy the custom image to App Service.
  • Configure environment variables.
  • Pull the image into App Service by using a managed identity.
  • Access diagnostic logs.
  • Enable CI/CD from Container Registry to App Service.
  • Connect to the container by using SSH.

Completing this tutorial incurs a small charge in your Azure account for the container registry and can incur more costs if you host the container for longer than a month.

Set up your initial environment

This tutorial requires version 2.0.80 or later of the Azure CLI. If you're using Azure Cloud Shell, the latest version is already installed.

After installing Docker, open a terminal window and verify that the docker is installed:

docker --version

Clone or download the sample app

You can obtain the sample for this tutorial via Git clone or download.

Clone the repo by using Git Bash

Clone the sample repository:

git clone https://github.com/Azure-Samples/docker-django-webapp-linux.git --config core.autocrlf=input

Ensure that you include the --config core.autocrlf=input argument to guarantee proper line endings in files that are used inside the Linux container.

Then navigate to the folder:

cd docker-django-webapp-linux

Download the ZIP from GitHub

Instead of using Git clone, you can go to https://github.com/Azure-Samples/docker-django-webapp-linux and select Code > Local > Download ZIP.

Unpack the ZIP file into a folder named docker-django-webapp-linux.

Then open a terminal window in the docker-django-webapp-linux folder.

(Optional) Examine the Docker file

Following is the file in the sample that's named Dockerfile. It describes the Docker image and contains configuration instructions.

FROM tiangolo/uwsgi-nginx-flask:python3.6

RUN mkdir /code
WORKDIR /code
ADD requirements.txt /code/
RUN pip install -r requirements.txt --no-cache-dir
ADD . /code/

# ssh
ENV SSH_PASSWD "root:Docker!"
RUN apt-get update \
        && apt-get install -y --no-install-recommends dialog \
        && apt-get update \
 && apt-get install -y --no-install-recommends openssh-server \
 && echo "$SSH_PASSWD" | chpasswd 

COPY sshd_config /etc/ssh/
COPY init.sh /usr/local/bin/
 
RUN chmod u+x /usr/local/bin/init.sh
EXPOSE 8000 2222

#CMD ["python", "/code/manage.py", "runserver", "0.0.0.0:8000"]
ENTRYPOINT ["init.sh"]
  • The first group of commands installs the app's requirements in the environment.
  • The second group of commands creates an SSH server to provide improved-security communication between the container and the host.
  • The last line, ENTRYPOINT ["init.sh"], invokes init.sh to start the SSH service and Python server.

Build and test the image locally

Note

Docker Hub imposes quotas on the number of anonymous pulls per IP and the number of authenticated pulls per free user. If you notice that your pulls from Docker Hub are being limited, try running docker login if you're not already logged in.

  1. Run the following command to build the image:

    docker build --tag appsvc-tutorial-custom-image .

  2. Test that the build works by running the Docker container locally:

    docker run -it -p 8000:8000 appsvc-tutorial-custom-image

    This docker run command specifies the port by using the -p argument and includes the name of the image. -it lets you stop it by using Ctrl+C.

    [!TIP] If you're running on Windows and see the error *standard_init_linux.go:211: exec user process caused "no such file or directory," the init.sh file contains CRLF line endings instead of the expected LF endings. This error happens if you used Git to clone the sample repository but omitted the --config core.autocrlf=input parameter. In this case, clone the repository again with the --config argument. You might also see the error if you edited init.sh and saved it with CRLF endings. In this case, save the file again with LF endings only.

  3. Browse to http://localhost:8000 to verify that the web app and container are functioning correctly.

    :::image type="content" source="./media/app-service-linux-using-custom-docker-image/app-service-linux-browse-local.png" alt-text="Screenshot of the test results.":::

Create a user-assigned managed identity

App Service can use either a default managed identity or a user-assigned managed identity to authenticate with a container registry. In this tutorial, you'll use a user-assigned managed identity.

Azure CLI

  1. Run the az group create command to create a resource group:

    az group create --name msdocs-custom-container-tutorial --location westeurope

    You can change the --location value to specify a region near you.

  2. Create a managed identity in the resource group:

    az identity create --name myID --resource-group msdocs-custom-container-tutorial

Azure portal

  1. In the Azure portal:

    1. Enter Managed Identities in the search box at the top of the Azure portal.

    2. Select the item labeled Managed Identities under the Services heading.

    3. Select Create. You can also go to Create User Assigned Managed Identity directly.

      :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-managed-identity-1.png" alt-text="Screenshot showing how to use the search box to find the Create User Assigned Managed Identity page." lightbox="./media/tutorial-custom-container/azure-portal-create-managed-identity-1.png":::

  2. On the Create User Assigned Managed Identity page:

    1. In Subscription, select the subscription you want to create your resources in.

    2. In Resource group, select Create new, enter the name msdocs-custom-container-tutorial for the resource group, and then select OK.

    3. In Region, select West Europe, or a region near you.

    4. In Name, enter myID.

      :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-managed-identity-2.png" alt-text="Screenshot showing how to configure a new managed identity." lightbox="./media/tutorial-custom-container/azure-portal-create-managed-identity-2.png":::

  3. On the Review + create tab, select Create.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-managed-identity-3.png" alt-text="Screenshot showing the final steps for creating the managed identity." lightbox="./media/tutorial-custom-container/azure-portal-create-managed-identity-3.png":::

  4. When the creation of the identity is complete, you can open its management page by selecting Go to resource.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-managed-identity-4.png" alt-text="Screenshot showing how to open the management page of the new managed identity." lightbox="./media/tutorial-custom-container/azure-portal-create-managed-identity-4.png":::

Create a container registry

Azure CLI

  1. Create a container registry by using the following az acr create command. Replace <registry-name> with a unique name for your registry. The name must contain only letters and numbers, and must be unique across all of Azure.

    az acr create --name <registry-name> --resource-group msdocs-custom-container-tutorial --sku Basic --admin-enabled true

    The --admin-enabled parameter lets you push images to the registry by using administrative credentials.

  2. Retrieve the administrative credentials by running the az credential acr show command:

    az acr credential show --resource-group msdocs-custom-container-tutorial --name <registry-name>

    The JSON output of this command provides two passwords along with the registry's user name.

Azure portal

  1. In the Azure portal:

    1. Enter Container registries in the search box at the top of the Azure portal.
    2. Select the item labeled Container registries under the Services heading.
    3. Select Create.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-container-registry-1.png" alt-text="Screenshot showing how to use the search box to find the Create container registry page." lightbox="./media/tutorial-custom-container/azure-portal-create-container-registry-1.png":::

  2. On the Create container registry page:

    1. In Subscription, select the subscription you used earlier.
    2. In Resource group, select msdocs-custom-container-tutorial.
    3. In Registry name, enter a unique name for your container registry.
    4. In Location, select West Europe, or the same region as your managed identity.
    5. In Pricing plan, select Basic.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-container-registry-2.png" alt-text="Screenshot showing how to configure a new container registry." lightbox="./media/tutorial-custom-container/azure-portal-create-container-registry-2.png":::

  3. On the Review + create tab, select Create.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-container-registry-3.png" alt-text="Screenshot showing the final steps for creating a container registry." lightbox="./media/tutorial-custom-container/azure-portal-create-container-registry-3.png":::

  4. When the container registry is created, open its management page by selecting Go to resource.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-container-registry-4.png" alt-text="Screenshot showing how to open the management page of the new container registry." lightbox="./media/tutorial-custom-container/azure-portal-create-container-registry-4.png":::

  5. In the left pane, under Settings, select Access keys.

  6. Select the checkbox next to Admin user.

  7. Copy the values for Login server, Username, and password. You'll use them in the next step to sign in to the registry and push a Docker image.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-container-registry-5.png" alt-text="Screenshot showing how to enable administrative credentials for a container registry." lightbox="./media/tutorial-custom-container/azure-portal-create-container-registry-5.png":::

Push the sample image to Container Registry

In this section, you push the image to Container Registry, which is used by App Service later.

  1. From the local terminal where you built the sample image, use the docker login command to sign in to the container registry:

    docker login <registry-name>.azurecr.io --username <registry-username>

    Replace <registry-name> and <registry-username> with values from the previous steps. When prompted, type in one of the passwords from the previous section.

    Use the same registry name in all the remaining steps of this section.

  2. When the sign-in is successful, tag your local Docker image to the registry:

    docker tag appsvc-tutorial-custom-image <registry-name>.azurecr.io/appsvc-tutorial-custom-image:latest

  3. Use the docker push command to push the image to the registry:

    docker push <registry-name>.azurecr.io/appsvc-tutorial-custom-image:latest

    Uploading the image the first time might take a few minutes because it includes the base image. Subsequent uploads are typically faster.

    While you're waiting, you can complete the steps in the next section to configure App Service to deploy from the registry.

Authorize the managed identity for your registry

The managed identity you created doesn't yet have authorization to pull from the container registry. In this step, you enable the authorization.

Azure CLI

  1. Retrieve the principal ID for the managed identity:

    principalId=$(az identity show --resource-group msdocs-custom-container-tutorial --name myID --query principalId --output tsv)

  2. Retrieve the resource ID for the container registry:

    registryId=$(az acr show --resource-group msdocs-custom-container-tutorial --name <registry-name> --query id --output tsv)

  3. Grant the managed identity permission to access the container registry:

    az role assignment create --assignee $principalId --scope $registryId --role "AcrPull"

    For more information about these permissions, see What is Azure role-based access control?.

Azure portal

  1. Back on the management page for the container registry:

    1. In the left pane, select Access control (IAM).
    2. Select Add role assignment.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-grant-identity-to-registry-1.png" alt-text="Screenshot showing how to enable adding a role assignment for a container registry." lightbox="./media/tutorial-custom-container/azure-portal-grant-identity-to-registry-1.png":::

  2. On the Job function roles tab, select AcrPull in the list of roles.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-grant-identity-to-registry-2.png" alt-text="Screenshot showing how to enable pull permission on the container registry." lightbox="./media/tutorial-custom-container/azure-portal-grant-identity-to-registry-2.png":::

  3. On the Members tab, under Assign access to, select Managed identity.

  4. Under Members, select Select members.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-grant-identity-to-registry-3.png" alt-text="Screenshot showing how to select members for an RBAC role." lightbox="./media/tutorial-custom-container/azure-portal-grant-identity-to-registry-3.png":::

  5. In the Select managed identities pane, in Managed identity, select User-assigned managed identity.

  6. Select myID.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-grant-identity-to-registry-4.png" alt-text="Screenshot showing a user-assigned managed identity selected for role assignment." lightbox="./media/tutorial-custom-container/azure-portal-grant-identity-to-registry-4.png":::

  7. At the bottom of the Review + assign tab, select Review + assign.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-grant-identity-to-registry-5.png" alt-text="Screenshot showing the last step of role assignment." lightbox="./media/tutorial-custom-container/azure-portal-grant-identity-to-registry-5.png":::

Create the web app

Azure CLI

  1. Create an App Service plan by using the az appservice plan create command:

    az appservice plan create --name myAppServicePlan --resource-group msdocs-custom-container-tutorial --is-linux

    An App Service plan corresponds to the virtual machine that hosts the web app. By default, the previous command uses an inexpensive B1 pricing tier that's free for the first month. You can specify the tier by using the --sku parameter.

  2. Create the web app with the az webapp create command:

    az webapp create --resource-group msdocs-custom-container-tutorial --plan myAppServicePlan --name <app-name> --deployment-container-image-name <registry-name>.azurecr.io/appsvc-tutorial-custom-image:latest

    Replace <app-name> with a name for the web app. The name must be unique across all of Azure. Also replace <registry-name> with the name of your registry from the previous section.

    [!TIP] You can retrieve the web app's container settings at any time with the command az webapp config container show --name <app-name> --resource-group msdocs-custom-container-tutorial. The image is specified in the property DOCKER_CUSTOM_IMAGE_NAME. When the web app is deployed through Azure DevOps or Azure Resource Manager templates, the image can also appear in a property named LinuxFxVersion. Both properties serve the same purpose. If both are present in the web app's configuration, LinuxFxVersion takes precedence.

Azure portal

  1. In the Azure portal:

    1. Enter app in the search box at the top of the Azure portal.

    2. Select the item labeled App Services under the Services heading.

    3. Select Create > Web App. You can also go to Create Web App directly.

      :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-app-service-1.png" alt-text="Screenshot showing how to use the search box to find the Create Web App page." lightbox="./media/tutorial-custom-container/azure-portal-create-app-service-1.png":::

    4. On the Create Web App page:

      1. In Subscription, select the subscription you used earlier.
      2. In Resource group, select msdocs-custom-container-tutorial.
      3. In Name, enter a unique app name. This name will be used in your app's default hostname: <app-name>.azurewebsites.net.
      4. In Publish, select Container.
      5. In Operating System, select Linux.
      6. In Region, select West Europe, or a region near you.
      7. In Linux Plan, select Create new, type a plan name, and then select OK.
      8. In Pricing plan, select Basic B1.

      :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-app-service-2.png" alt-text="Screenshot showing how to configure a new web app." lightbox="./media/tutorial-custom-container/azure-portal-create-app-service-2.png":::

    5. Select the Container tab.

    6. In Image Source, select Azure Container Registry.

    7. In Registry, select the container registry you created earlier.

    8. In Identity, select myID.

    9. In Image, select appsvc-tutorial-custom-image.

    10. In Tag, select latest.

      :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-app-service-4.png" alt-text="Screenshot showing how to configure Docker settings." lightbox="./media/tutorial-custom-container/azure-portal-create-app-service-4.png":::

    11. On the Review + create tab, select Create.

      :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-app-service-5.png" alt-text="Screenshot showing the last step for creating a web app." lightbox="./media/tutorial-custom-container/azure-portal-create-app-service-5.png":::

    12. When the web app is created, you can open its management page by selecting Go to resource.

      :::image type="content" source="./media/tutorial-custom-container/azure-portal-create-app-service-6.png" alt-text="Screenshot showing how to open the management page of the new web app." lightbox="./media/tutorial-custom-container/azure-portal-create-app-service-6.png":::

Configure the web app

In this step, you configure the web app as follows:

  • Configure the app to send requests to port 8000. The sample container is listening on port 8000 for web requests.
  • Configure your app to use the managed identity to pull images from your container registry.
  • Configure continuous deployment from the container registry. (Every image push to the registry will trigger your app to pull the new image.) This step isn't needed to configure your web app to pull from your container registry, but it can notify the web app when a new image is pushed to the registry. If you don't complete this step, you must manually trigger an image pull by restarting the web app.

Azure CLI

  1. Use az webapp config appsettings set to set the WEBSITES_PORT environment variable as expected by the app code:

    az webapp config appsettings set --resource-group msdocs-custom-container-tutorial --name <app-name> --settings WEBSITES_PORT=8000

    Replace <app-name> with the name you used in the previous step.

  2. Enable the user-assigned managed identity in the web app by using the az webapp identity assign command:

    id=$(az identity show --resource-group msdocs-custom-container-tutorial --name myID --query id --output tsv)
az webapp identity assign --resource-group msdocs-custom-container-tutorial --name <app-name> --identities $id

    Replace <app-name> with the name you used in the previous step.

  3. Configure your app to pull from Container Registry by using managed identities.

    appConfig=$(az webapp config show --resource-group msdocs-custom-container-tutorial --name <app-name> --query id --output tsv)
az resource update --ids $appConfig --set properties.acrUseManagedIdentityCreds=True

    Replace <app-name> with the name you used in the previous step.

  4. Set the client ID your web app uses to pull from Container Registry. This step isn't required if you use the system-assigned managed identity.

    clientId=$(az identity show --resource-group msdocs-custom-container-tutorial --name myID --query clientId --output tsv)
az resource update --ids $appConfig --set properties.AcrUserManagedIdentityID=$clientId

  5. Enable CI/CD in App Service.

    cicdUrl=$(az webapp deployment container config --enable-cd true --name <app-name> --resource-group msdocs-custom-container-tutorial --query CI_CD_URL --output tsv)

    CI_CD_URL is a URL that App Service generates for you. Your registry should use this URL to notify App Service that an image push occurred. It doesn't actually create the webhook for you.

  6. Create a webhook in your container registry. Use the CI_CD_URL you got in the last step.

    az acr webhook create --name appserviceCD --registry <registry-name> --uri $cicdUrl --actions push --scope appsvc-tutorial-custom-image:latest

  7. To test if your webhook is configured properly, ping the webhook and see whether you get a 200 OK response.

    eventId=$(az acr webhook ping --name appserviceCD --registry <registry-name> --query id --output tsv)
az acr webhook list-events --name appserviceCD --registry <registry-name> --query "[?id=='$eventId'].eventResponseMessage"

    [!TIP] To see all information about all webhook events, remove the --query parameter.

    If you're streaming the container log, you should see a Starting container for site message after the webhook ping because the webhook triggers the app to restart.

Azure portal

  1. In the left pane of your web app's management page, under Settings, select Environment variables.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-configure-app-service-1.png" alt-text="Screenshot showing how to open the Configuration page." lightbox="./media/tutorial-custom-container/azure-portal-configure-app-service-1.png":::

  2. On the Environment variables page:

    1. Select Add.

    2. In Name, enter WEBSITES_PORT.

    3. In Value, enter 8000.

    4. Select Apply in the Add/Edit application setting pane, and then select Apply again. Confirm the change.

      The WEBSITES_PORT setting specifies the container port to forward web requests to. For more information, see Custom containers.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-configure-app-service-2.png" alt-text="Screenshot showing how to set the WEBSITES_PORT app setting." lightbox="./media/tutorial-custom-container/azure-portal-configure-app-service-2.png":::

  3. In the left pane, select Identity.

  4. On the Identity page, on the User assigned tab, select Add.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-configure-app-service-3.png" alt-text="Screenshot showing how to add a user-assigned managed identity to a web app." lightbox="./media/tutorial-custom-container/azure-portal-configure-app-service-3.png":::

  5. Select myID, and then select Add.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-configure-app-service-4.png" alt-text="Screenshot showing how to add a user-assigned managed identity." lightbox="./media/tutorial-custom-container/azure-portal-configure-app-service-4.png":::

  6. In the left pane, under Deployment, select Deployment Center. Then do the following on the Deployment Center page:

    1. On the Containers tab, select the deployment that's listed.
    2. In the Edit container pane, under Authentication, ensure that Managed Identity is selected.
    3. In Identity, ensure that myID is selected. If you made changes, select Apply.
    4. Back on the Deployment Center page, select Continuous deployment for the main container, and then select Apply.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-configure-app-service-5.png" alt-text="Screenshot showing the Containers tab on the Deployment Center page. Continuous deployment is selected." lightbox="./media/tutorial-custom-container/azure-portal-configure-app-service-5.png":::

  7. On the Deployment Center page, select the Logs tab. On this tab, you can see log messages for pulling the image and starting the container. Later, you'll learn how to see generated console messages from within the container.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-configure-app-service-6.png" alt-text="Screenshot showing log messages for pulling an image and starting the container." lightbox="./media/tutorial-custom-container/azure-portal-configure-app-service-6.png":::

Browse to the web app

Azure CLI

To test the app, browse to https://<app-name>.azurewebsites.net. Replace <app-name> with the name of your web app.

Azure portal

  1. On the App Service page, in the left pane, select Overview.

  2. Select the Browse button at the top of the page.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-browse-app-1.png" alt-text="Screenshot showing how to browse to the web app from the Azure portal." lightbox="./media/tutorial-custom-container/azure-portal-browse-app-1.png":::

The first time you attempt to access the app, it might take some time for the app to respond because App Service must pull the entire image from the registry. If the browser times out, just refresh the page. After the initial image is pulled, subsequent tests will run much faster.

:::image type="content" source="./media/app-service-linux-using-custom-docker-image/app-service-linux-browse-azure.png" alt-text="Screenshot of the web app running in a browser.":::

Access diagnostic logs

Azure CLI

While you're waiting for the App Service to pull in the image, it's helpful to see exactly what App Service is doing by streaming the container logs to your terminal.

  1. Turn on container logging:

    az webapp log config --name <app-name> --resource-group msdocs-custom-container-tutorial --docker-container-logging filesystem

  2. Enable the log stream:

    az webapp log tail --name <app-name> --resource-group msdocs-custom-container-tutorial

    If you don't see console logs immediately, check again in 30 seconds.

    You can also inspect the log files from a browser by going to https://<app-name>.scm.azurewebsites.net/api/logs/docker.

  3. To stop log streaming at any time, select Ctrl+C.

Azure portal

On the Deployment Center page, you can already see the log messages for pulling and starting the container. In this step, you enable logging of the console output from within the container.

  1. On the App Service page:

    1. In the left pane, under Monitoring, select App Service logs.
    2. In Application logging, select File System.
    3. Select Save.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-stream-diagnostic-logs-1.png" alt-text="Screenshot showing how to enable diagnostic logging for the custom container." lightbox="./media/tutorial-custom-container/azure-portal-stream-diagnostic-logs-1.png":::

  2. In the left pane, under Monitoring, select Log stream. You should see the container's console output in the log stream.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-stream-diagnostic-logs-2.png" alt-text="Screenshot showing log messages that contain the container's console output." lightbox="./media/tutorial-custom-container/azure-portal-stream-diagnostic-logs-2.png":::

Modify the app code and redeploy

In this section, you make a change to the web app code, rebuild the image, and then push it to your container registry. App Service then automatically pulls the updated image from the registry to update the running web app.

  1. In your local docker-django-webapp-linux folder, open the file app/templates/app/index.html.

  2. Change the first HTML element to match the following code.

    <nav class="navbar navbar-inverse navbar-fixed-top">
  <div class="container">
    <div class="navbar-header">
      <a class="navbar-brand" href="#">Azure App Service - Updated Here!</a>
    </div>
  </div>
</nav>

  3. Save your changes.

  4. Go to the docker-django-webapp-linux folder and rebuild the image:

    docker build --tag appsvc-tutorial-custom-image .

  5. Update the image's tag to latest:

    docker tag appsvc-tutorial-custom-image <registry-name>.azurecr.io/appsvc-tutorial-custom-image:latest

    Replace <registry-name> with the name of your registry.

  6. Push the image to the registry:

    docker push <registry-name>.azurecr.io/appsvc-tutorial-custom-image:latest

  7. When the image push is complete, the webhook notifies App Service about the push, and App Service tries to pull in the updated image. Wait a few minutes, and then verify that the update is deployed by going to https://<app-name>.azurewebsites.net.

Connect to the container by using SSH

SSH enables improved-security communication between a container and a client. To enable an SSH connection to your container, you must configure your custom image for it. When the container is running, you can open an SSH connection.

Configure the container for SSH

The sample app used in this tutorial already has the necessary configuration in Dockerfile, which installs the SSH server and also sets the sign-in credentials. This section is informational only. To connect to the container, skip to the next section.

ENV SSH_PASSWD "root:Docker!"
RUN apt-get update \
        && apt-get install -y --no-install-recommends dialog \
        && apt-get update \
  && apt-get install -y --no-install-recommends openssh-server \
  && echo "$SSH_PASSWD" | chpasswd

Note

This configuration doesn't allow external connections to the container. SSH is available only through the Kudu/SCM site. The Kudu/SCM site is authenticated with your Azure account. root:Docker! shouldn't be altered when you use SSH. SCM/KUDU uses your Azure portal credentials. Changing this value will result in an error when you use SSH.

Dockerfile also copies the sshd_config file to the /etc/ssh/ folder and exposes port 2222 on the container:

COPY sshd_config /etc/ssh/

# ...

EXPOSE 8000 2222

Port 2222 is an internal port accessible only by containers within the bridge network of a private virtual network.

Finally, the entry script, init.sh, starts the SSH server.

#!/bin/bash
service ssh start

Open the SSH connection to the container

Azure CLI

  1. Go to https://<app-name>.scm.azurewebsites.net/webssh/host and sign in with your Azure account. Replace <app-name> with the name of your web app.

  2. When you sign in, you're redirected to an informational page for the web app. Select SSH at the top of the page to open the shell and use commands.

    For example, you can examine the processes running within the app by using the top command.

Azure portal

  1. On the App Service page:

    1. In the left pane, under Development Tools, select SSH.
    2. Select Go.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-start-ssh-container-session-1.png" alt-text="Screenshot showing how to open an SSH session with your custom container." lightbox="./media/tutorial-custom-container/azure-portal-start-ssh-container-session-1.png":::

  2. The SSH session is opened in a new browser tab. Wait for the status bar at the bottom to show a green SSH CONNECTION ESTABLISHED message. You can then run commands from within the container. Configuration changes made to your container aren't persisted across app restarts.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-start-ssh-container-session-2.png" alt-text="Screenshot showing an SSH session with a custom container." lightbox="./media/tutorial-custom-container/azure-portal-start-ssh-container-session-2.png":::

Clean up resources

Azure CLI

The resources you created in this article might incur ongoing costs. To clean up the resources, you only need to delete the resource group that contains them:

az group delete --name msdocs-custom-container-tutorial

Azure portal

  1. In the search box at the top of the Azure portal:

    1. Enter the resource group name.
    2. Select the resource group.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-delete-resource-group-1.png" alt-text="Screenshot showing how to search for and go to a resource group in the Azure portal." lightbox="./media/tutorial-custom-container/azure-portal-delete-resource-group-1.png":::

  2. On the resource group page, select Delete resource group.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-delete-resource-group-2.png" alt-text="Screenshot showing the location of the Delete resource group button in the Azure portal." lightbox="./media/tutorial-custom-container/azure-portal-delete-resource-group-2.png":::

  3. Enter the resource group name to confirm your deletion, and then select Delete.

    :::image type="content" source="./media/tutorial-custom-container/azure-portal-delete-resource-group-3.png" alt-text="A screenshot of the confirmation dialog for deleting a resource group in the Azure portal." lightbox="./media/tutorial-custom-container/azure-portal-delete-resource-group-3.png":::

::: zone-end

Next steps

What you learned:

::: zone pivot="container-windows"

[!div class="checklist"]

  • Deploy a custom image to a private container registry.
  • Deploy the custom image to App Service.
  • Update and redeploy the image.
  • Access diagnostic logs.
  • Connect to the container by using SSH.

::: zone-end

::: zone pivot="container-linux"

[!div class="checklist"]

  • Push a custom Docker image to Container Registry.
  • Deploy the custom image to App Service.
  • Configure environment variables.
  • Pull the image into App Service by using a managed identity.
  • Access diagnostic logs.
  • Enable CI/CD from Container Registry to App Service.
  • Connect to the container by using SSH.

::: zone-end

Go to the next tutorial:

[!div class="nextstepaction"]  Provide security with a custom domain and certificate

Or check out other resources:

[!div class="nextstepaction"] Configure a custom container

::: zone pivot="container-linux"

[!div class="nextstepaction"] Configure a sidecar container for a custom container in App Service ::: zone-end