• Configure Docker Container System
• Configure Docker Container To Use Proxy
• Configure Docker Container Logs
• Configure Docker Container
• Configure Docker Container Model
• Configure Docker Container Tote

Before you can use Docker, you'll need to install the container images. For more information, see docs for our container base images. Configure Docker with a configuration file. The preferred method for configuring the Docker Engine on Windows is using a configuration file. Change the Docker image of a custom container. To change an existing custom container app from the current Docker image to a new image, use the following command: az webapp config container set -name -resource-group -docker-custom-image-name docker-hub-repo/ Use an image from a private registry.

This article shows you how to configure a custom container to run on Azure App Service.

This guide provides key concepts and instructions for containerization of Windows apps in App Service. If you've never used Azure App Service, follow the custom container quickstart and tutorial first.

This guide provides key concepts and instructions for containerization of Linux apps in App Service. If you've never used Azure App Service, follow the custom container quickstart and tutorial first. There's also a multi-container app quickstart and tutorial.

Supported parent images

For your custom Windows image, you must choose the right parent image (base image) for the framework you want:

• To deploy .NET Framework apps, use a parent image based on the Windows Server Core Long-Term Servicing Channel (LTSC) release.
• To deploy .NET Core apps, use a parent image based on the Windows Server Nano Semi-Annual Servicing Channel (SAC) release.

It takes some time to download a parent image during app start-up. However, you can reduce start-up time by using one of the following parent images that are already cached in Azure App Service:

• mcr.microsoft.com/windows/servercore:2004
• mcr.microsoft.com/windows/servercore:ltsc2019
• mcr.microsoft.com/dotnet/framework/aspnet:4.8-windowsservercore-2004
• mcr.microsoft.com/dotnet/framework/aspnet:4.8-windowsservercore-ltsc2019
• mcr.microsoft.com/dotnet/core/runtime:3.1-nanoserver-2004
• mcr.microsoft.com/dotnet/core/runtime:3.1-nanoserver-1909
• mcr.microsoft.com/dotnet/core/runtime:3.1-nanoserver-1903
• mcr.microsoft.com/dotnet/core/runtime:3.1-nanoserver-1809
• mcr.microsoft.com/dotnet/core/aspnet:3.1-nanoserver-2004
• mcr.microsoft.com/dotnet/core/aspnet:3.1-nanoserver-1909
• mcr.microsoft.com/dotnet/core/aspnet:3.1-nanoserver-1903
• mcr.microsoft.com/dotnet/core/aspnet:3.1-nanoserver-1809

Change the Docker image of a custom container

To change an existing custom container app from the current Docker image to a new image, use the following command:

Use an image from a private registry

To use an image from a private registry, such as Azure Container Registry, run the following command:

For <username> and <password>, supply the login credentials for your private registry account.

I don't see the updated container

If you change your Docker container settings to point to a new container, it may take a few minutes before the app serves HTTP requests from the new container. While the new container is being pulled and started, App Service continues to serve requests from the old container. Only when the new container is started and ready to receive requests does App Service start sending requests to it.

How container images are stored

The first time you run a custom Docker image in App Service, App Service does a docker pull and pulls all image layers. These layers are stored on disk, like if you were using Docker on-premises. Each time the app restarts, App Service does a docker pull, but only pulls layers that have changed. If there have been no changes, App Service uses existing layers on the local disk.

If the app changes compute instances for any reason, such as scaling up and down the pricing tiers, App Service must pull down all layers again. The same is true if you scale out to add additional instances. There are also rare cases where the app instances may change without a scale operation.

Configure port number

Configure Docker Container System

By default, App Service assumes your custom container is listening on port 80. If your container listens to a different port, set the WEBSITES_PORT app setting in your App Service app. You can set it via the Cloud Shell. In Bash:

In PowerShell:

App Service currently allows your container to expose only one port for HTTP requests.

Configure environment variables

Your custom container may use environment variables that need to be supplied externally. You can pass them in via the Cloud Shell. In Bash:

In PowerShell:

When your app runs, the App Service app settings are injected into the process as environment variables automatically. You can verify container environment variables with the URL https://<app-name>.scm.azurewebsites.net/Env).

If your app uses images from a private registry or from Docker Hub, credentials for accessing the repository are saved in environment variables: DOCKER_REGISTRY_SERVER_URL, DOCKER_REGISTRY_SERVER_USERNAME and DOCKER_REGISTRY_SERVER_PASSWORD. Because of security risks, none of these reserved variable names are exposed to the application.

For IIS or .NET Framework (4.0 or above) based containers, they're injected into System.ConfigurationManager as .NET app settings and connection strings automatically by App Service. For all other language or framework, they're provided as environment variables for the process, with one of the following corresponding prefixes:

Configure Docker Container To Use Proxy

• APPSETTING_
• SQLCONTR_
• MYSQLCONTR_
• SQLAZURECOSTR_
• POSTGRESQLCONTR_
• CUSTOMCONNSTR_

This method works both for single-container apps or multi-container apps, where the environment variables are specified in the docker-compose.yml file.

Use persistent shared storage

You can use the C:home directory in your app's file system to persist files across restarts and share them across instances. The C:home in your app is provided to enable your container app to access persistent storage.

When persistent storage is disabled, writes to the C:home directory aren't persisted. Docker host logs and container logs are saved in a default persistent shared storage that is not attached to the container. When persistent storage is enabled, all writes to the C:home directory are persisted and can be accessed by all instances of a scaled-out app, and log are accessible at C:homeLogFiles.

You can use the /home directory in your app's file system to persist files across restarts and share them across instances. The /home in your app is provided to enable your container app to access persistent storage.

When persistent storage is disabled, then writes to the /home directory aren't persisted across app restarts or across multiple instances. The only exception is the /home/LogFiles directory, which is used to store the Docker and container logs. When persistent storage is enabled, all writes to the /home directory are persisted and can be accessed by all instances of a scaled-out app.

By default, persistent storage is disabled and the setting is not exposed in the app settings. To enable it, set the WEBSITES_ENABLE_APP_SERVICE_STORAGE app setting via the Cloud Shell. In Bash:

In PowerShell:

Note

Configure Docker Container Logs

You can also configure your own persistent storage.

Detect HTTPS session

App Service terminates TLS/SSL at the front ends. That means that TLS/SSL requests never get to your app. You don't need to, and shouldn't implement any support for TLS/SSL into your app.

The front ends are located inside Azure data centers. If you use TLS/SSL with your app, your traffic across the Internet will always be safely encrypted.

Customize ASP.NET machine key injection

During the container start, automatically generated keys are injected into the container as the machine keys for ASP.NET cryptographic routines. You can find these keys in your container by looking for the following environment variables: MACHINEKEY_Decryption, MACHINEKEY_DecryptionKey, MACHINEKEY_ValidationKey, MACHINEKEY_Validation.

The new keys at each restart may reset ASP.NET forms authentication and view state, if your app depends on them. To prevent the automatic regeneration of keys, set them manually as App Service app settings.

Connect to the container

You can connect to your Windows container directly for diagnostic tasks by navigating to https://<app-name>.scm.azurewebsites.net/DebugConsole. Here's how it works:

• The debug console lets you execute interactive commands, such as starting PowerShell sessions, inspecting registry keys, and navigate the entire container file system.
• It functions separately from the graphical browser above it, which only shows the files in your shared storage.
• In a scaled-out app, the debug console is connected to one of the container instances. You can select a different instance from the Instance dropdown in the top menu.
• Any change you make to the container from within the console does not persist when your app is restarted (except for changes in the shared storage), because it's not part of the Docker image. To persist your changes, such as registry settings and software installation, make them part of the Dockerfile.

Access diagnostic logs

App Service logs actions by the Docker host as well as activities from within the container. Logs from the Docker host (platform logs) are shipped by default, but application logs or web server logs from within the container need to be enabled manually. For more information, see Enable application logging and Enable web server logging.

There are several ways to access Docker logs:

In Azure portal

Docker logs are displayed in the portal, in the Container Settings page of your app. The logs are truncated, but you can download all the logs clicking Download.

From the Kudu console

Navigate to https://<app-name>.scm.azurewebsites.net/DebugConsole and click the LogFiles folder to see the individual log files. To download the entire LogFiles directory, click the Download icon to the left of the directory name. You can also access this folder using an FTP client.

In the console terminal, you can't access the C:homeLogFiles folder by default because persistent shared storage is not enabled. To enable this behavior in the console terminal, enable persistent shared storage.

If you try to download the Docker log that is currently in use using an FTP client, you may get an error because of a file lock.

With the Kudu API

Navigate directly to https://<app-name>.scm.azurewebsites.net/api/logs/docker to see metadata for the Docker logs. You may see more than one log file listed, and the href property lets you download the log file directly.

To download all the logs together in one ZIP file, access https://<app-name>.scm.azurewebsites.net/api/logs/docker/zip.

Customize container memory

By default all Windows Containers deployed in Azure App Service are limited to 1 GB RAM. You can change this value by providing the WEBSITE_MEMORY_LIMIT_MB app setting via the Cloud Shell. In Bash:

In PowerShell:

The value is defined in MB and must be less and equal to the total physical memory of the host. For example, in an App Service plan with 8 GB RAM, the cumulative total of WEBSITE_MEMORY_LIMIT_MB for all the apps must not exceed 8 GB. Information on how much memory is available for each pricing tier can be found in App Service pricing, in the Premium Container (Windows) Plan section.

Customize the number of compute cores

By default, a Windows container runs with all available cores for your chosen pricing tier. You may want to reduce the number of cores that your staging slot uses, for example. To reduce the number of cores used by a container, set the WEBSITE_CPU_CORES_LIMIT app setting to the preferred number of cores. You can set it via the Cloud Shell. In Bash:

In PowerShell:

Note

Updating the app setting triggers automatic restart, causing minimal downtime. For a production app, consider swapping it into a staging slot, change the app setting in the staging slot, and then swap it back into production.

Verify your adjusted number by going to the Kudu Console (https://<app-name>.scm.azurewebsites.net) and typing in the following commands using PowerShell. Each command outputs a number.

The processors may be multicore or hyperthreading processors. Information on how many cores are available for each pricing tier can be found in App Service pricing, in the Premium Container (Windows) Plan section.

Customize health ping behavior

App Service considers a container to be successfully started when the container starts and responds to an HTTP ping. The health ping request contains the header User-Agent= 'App Service Hyper-V Container Availability Check'. If the container starts but does not respond to a ping after a certain amount of time, App Service logs an event in the Docker log, saying that the container didn't start.

If your application is resource-intensive, the container might not respond to the HTTP ping in time. To control the actions when HTTP pings fail, set the CONTAINER_AVAILABILITY_CHECK_MODE app setting. You can set it via the Cloud Shell. In Bash:

In PowerShell:

The following table shows the possible values:

Support for Group Managed Service Accounts

Group Managed Service Accounts (gMSAs) are currently not supported in Windows containers in App Service.

Enable SSH

SSH enables secure communication between a container and a client. In order for a custom container to support SSH, you must add it into your Docker image itself.

Tip

All built-in Linux containers in App Service have added the SSH instructions in their image repositories. You can go through the following instructions with the Node.js 10.14 repository to see how it's enabled there. The configuration in the Node.js built-in image is slightly different, but the same in principle.

• Add an sshd_config file to your repository, like the following example.

  Note

  This file configures OpenSSH and must include the following items:

  • Port must be set to 2222.
  • Ciphers must include at least one item in this list: aes128-cbc,3des-cbc,aes256-cbc.
  • MACs must include at least one item in this list: hmac-sha1,hmac-sha1-96.

• In your Dockerfile, add the following commands:

  This configuration doesn't allow external connections to the container. Port 2222 of the container is accessible only within the bridge network of a private virtual network, and is not accessible to an attacker on the internet.

• In the start-up script for your container, start the SSH server.

Access diagnostic logs

You can access the console logs generated from inside the container.

First, turn on container logging by running the following command:

Replace <app-name> and <resource-group-name> with the names appropriate for your web app.

Once container logging is turned on, run the following command to see the log stream:

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

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

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

Configure multi-container apps

Use persistent storage in Docker Compose

Multi-container apps like WordPress need persistent storage to function properly. To enable it, your Docker Compose configuration must point to a storage location outside your container. Storage locations inside your container don't persist changes beyond app restart.

Enable persistent storage by setting the WEBSITES_ENABLE_APP_SERVICE_STORAGE app setting, using the az webapp config appsettings set command in Cloud Shell.

In your docker-compose.yml file, map the volumes option to ${WEBAPP_STORAGE_HOME}.

WEBAPP_STORAGE_HOME is an environment variable in App Service that is mapped to persistent storage for your app. For example:

Preview limitations

Multi-container is currently in preview. The following App Service platform features are not supported:

Configure Docker Container

• Authentication / Authorization
• Managed Identities
• CORS

Docker Compose options

The following lists show supported and unsupported Docker Compose configuration options:

Supported options

• command
• entrypoint
• environment
• image
• ports
• restart
• services
• volumes

Configure Docker Container Model

Unsupported options

• build (not allowed)
• depends_on (ignored)
• networks (ignored)
• secrets (ignored)
• ports other than 80 and 8080 (ignored)

Note

Any other options not explicitly called out are ignored in Public Preview.

robots933456 in logs

You may see the following message in the container logs:

You can safely ignore this message. /robots933456.txt is a dummy URL path that App Service uses to check if the container is capable of serving requests. A 404 response simply indicates that the path doesn't exist, but it lets App Service know that the container is healthy and ready to respond to requests.

Configure Docker Container Tote

Next steps

Or, see additional resources:

Estimated reading time: 2 minutes

If your container needs to use an HTTP, HTTPS, or FTP proxy server, you canconfigure it in different ways:

• In Docker 17.07 and higher, you canconfigure the Docker client to passproxy information to containers automatically.

• In Docker 17.06 and lower, you mustset appropriate environment variableswithin the container. You can do this when you build the image (which makesthe image less portable) or when you create or run the container.

Configure the Docker client

1. On the Docker client, create or edit the file ~/.docker/config.json in thehome directory of the user which starts containers. Add JSON such as thefollowing, substituting the type of proxy with httpsProxy or ftpProxy ifnecessary, and substituting the address and port of the proxy server. Youcan configure multiple proxy servers at the same time.

   You can optionally exclude hosts or ranges from going through the proxyserver by setting a noProxy key to one or more comma-separated IPaddresses or hosts. Using the * character as a wildcard for hosts and using CIDR notation for IP addresses is supported asshown in this example.

   Save the file.

2. When you create or start new containers, the environment variables areset automatically within the container.

Use environment variables

Set the environment variables manually

When you build the image, or using the --env flag when you create or run thecontainer, you can set one or more of the following variables to the appropriatevalue. This method makes the image less portable, so if you have Docker 17.07or higher, you should configure the Docker clientinstead.