Configure a custom container for Azure App Service

This guide provides key concepts and instructions for containerization of Windows apps in App Service. New Azure App Service users should follow the custom container quickstart and tutorial first.

This guide provides key concepts and instructions for containerization of Linux apps in App Service. If are new to Azure App Service, follow the custom container quickstart and tutorial first. For sidecar containers (preview), see Tutorial: Configure a sidecar container for custom container in Azure App Service (preview).

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 2019 Core Long-Term Servicing Channel (LTSC) release.
• To deploy .NET Core apps, use a parent image based on the Windows Server 2019 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:ltsc2022
• mcr.microsoft.com/windows/servercore:ltsc2019
• mcr.microsoft.com/dotnet/framework/aspnet:4.8-windowsservercore-ltsc2022
• mcr.microsoft.com/dotnet/framework/aspnet:4.8-windowsservercore-ltsc2019
• mcr.microsoft.com/dotnet/runtime:6.0-nanoserver-ltsc2022
• mcr.microsoft.com/dotnet/runtime:6.0-nanoserver-1809
• mcr.microsoft.com/dotnet/aspnet:6.0-nanoserver-ltsc2022
• mcr.microsoft.com/dotnet/aspnet:6.0-nanoserver-1809

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:

• 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.

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

When persistent storage is disabled, then writes to the C:\home directory aren't persisted across app restarts or across multiple instances. 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. Additionally, any contents inside the C:\home directory of the container are overwritten by any existing files already present on the persistent storage when the container starts.

The only exception is the C:\home\LogFiles directory, which is used to store the container and application logs. This folder always persists upon app restarts if application logging is enabled with the File System option, independently of the persistent storage being enabled or disabled. In other words, enabling or disabling the persistent storage doesn't affect the application logging behavior.

By default, persistent storage is enabled on Windows custom containers. To disable it, set the WEBSITES_ENABLE_APP_SERVICE_STORAGE app setting value to false via the Cloud Shell. In Bash:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings WEBSITES_ENABLE_APP_SERVICE_STORAGE=false

In PowerShell:

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings @{"WEBSITES_ENABLE_APP_SERVICE_STORAGE"=false}

You can use the /home directory in your custom container file system to persist files across restarts and share them across instances. The /home directory is provided to enable your custom container to access persistent storage. Saving data within /home contributes to the storage space quota included with your App Service Plan.

When persistent storage is disabled, then writes to the /home directory aren't persisted across app restarts or across multiple instances. 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. Additionally, any contents inside the /home directory of the container are overwritten by any existing files already present on the persistent storage when the container starts.

The only exception is the /home/LogFiles directory, which is used to store the container and application logs. This folder always persists upon app restarts if application logging is enabled with the File System option, independently of the persistent storage being enabled or disabled. In other words, enabling or disabling the persistent storage doesn't affect the application logging behavior.

It's recommended to write data to /home or a mounted Azure storage path. Data written outside these paths isn't persistent during restarts and is saved to platform-managed host disk space separate from the App Service Plans file storage quota.

By default, persistent storage is disabled on Linux custom containers. To enable it, set the WEBSITES_ENABLE_APP_SERVICE_STORAGE app setting value to true via the Azure CLI or Azure PowerShell. In Bash:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings WEBSITES_ENABLE_APP_SERVICE_STORAGE=true

In PowerShell:

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings @{"WEBSITES_ENABLE_APP_SERVICE_STORAGE"=true}

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 might 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.chinacloudsites.cn/ and choosing the SSH option. A direct SSH session with your container is established in which you can run commands inside your container.

• It functions separately from the graphical browser above it, which only shows the files in your shared storage.
• In a scaled-out app, the SSH session is connected to one of the container instances. You can select a different instance from the Instance dropdown in the top Kudu menu.
• Any change you make to the container from within the SSH session doesn't 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 and 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:

• Azure portal
• Kudu
• Kudu API
• Azure monitor

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 selecting Download.

From Kudu

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

In the SSH terminal, you can't access the C:\home\LogFiles folder by default because persistent shared storage isn't 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 by using an FTP client, you might get an error because of a file lock.

With the Kudu API

Navigate directly to https://<app-name>.scm.chinacloudsites.cn/api/logs/docker to see metadata for the Docker logs. You might 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.chinacloudsites.cn/api/logs/docker/zip.

Customize container memory

By default all Windows Containers deployed in Azure App Service have a memory limit configured. The following table lists the default settings per App Service Plan SKU.

You can change this value by providing the WEBSITE_MEMORY_LIMIT_MB app setting via the Azure CLI or Azure PowerShell. In Bash:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings WEBSITE_MEMORY_LIMIT_MB=2000

In PowerShell:

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings @{"WEBSITE_MEMORY_LIMIT_MB"=2000}

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.

Customize the number of compute cores

By default, a Windows container runs with all available cores for your chosen pricing tier. You might 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 Azure CLI. In Bash:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --slot staging --settings WEBSITE_CPU_CORES_LIMIT=1

In PowerShell:

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings @{"WEBSITE_CPU_CORES_LIMIT"=1}

Verify your adjusted number by opening an SSH session from the portal or via the Kudu portal (https://<app-name>.scm.chinacloudsites.cn/webssh/host) and typing in the following commands using PowerShell. Each command outputs a number.

Get-ComputerInfo | ft CsNumberOfLogicalProcessors # Total number of enabled logical processors. Disabled processors are excluded.
Get-ComputerInfo | ft CsNumberOfProcessors # Number of physical processors.

The processors might be multicore or hyperthreading processors. Information on how many cores are available for each pricing tier can be found in App Service pricing.

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 doesn't respond pings 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 Azure CLI. In Bash:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings CONTAINER_AVAILABILITY_CHECK_MODE="ReportOnly"

In PowerShell:

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -AppSettings @{"CONTAINER_AVAILABILITY_CHECK_MODE"="ReportOnly"}

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

Secure Shell (SSH) is commonly used to execute administrative commands remotely from a command-line terminal. In order to enable the Azure portal SSH console feature with custom containers, the following steps are required:

1. Create a standard sshd_config file with the following example contents and place it on the application project root directory:

   Port 			2222
   ListenAddress 		0.0.0.0
   LoginGraceTime 		180
   X11Forwarding 		yes
   Ciphers aes128-cbc,3des-cbc,aes256-cbc,aes128-ctr,aes192-ctr,aes256-ctr
   MACs hmac-sha1,hmac-sha1-96
   StrictModes 		yes
   SyslogFacility 		DAEMON
   PasswordAuthentication 	yes
   PermitEmptyPasswords 	no
   PermitRootLogin 	yes
   Subsystem sftp internal-sftp
   

   Note

   This file configures OpenSSH and must include the following items in order to comply with the Azure portal SSH feature:

   • 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.

2. Create an entrypoint script with the name entrypoint.sh (or change any existing entrypoint file) and add the command to start the SSH service, along with the application startup command. The following example demonstrates starting a Python application. Replace the last command according to the project language/stack:

   • Debian
   • Alpine

   #!/bin/sh
   set -e
   service ssh start
   exec gunicorn -w 4 -b 0.0.0.0:8000 app:app
   

3. Add to the Dockerfile the following instructions according to the base image distribution. These instructions copy the new files, install OpenSSH server, set proper permissions and configure the custom entrypoint, and expose the ports required by the application and SSH server, respectively:

   • Debian
   • Alpine

   COPY entrypoint.sh ./
   
   # Start and enable SSH
   RUN apt-get update \
       && apt-get install -y --no-install-recommends dialog \
       && apt-get install -y --no-install-recommends openssh-server \
       && echo "root:Docker!" | chpasswd \
       && chmod u+x ./entrypoint.sh
   COPY sshd_config /etc/ssh/
   
   EXPOSE 8000 2222
   
   ENTRYPOINT [ "./entrypoint.sh" ] 
   

   Note

   The root password must be exactly Docker! as it's used by App Service to let you access the SSH session with the container. 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 isn't accessible to an attacker on the internet.

4. Rebuild and push the Docker image to the registry, and then test the Web App SSH feature on Azure portal.

Further troubleshooting information is available at the Azure App Service blog: Enabling SSH on Linux Web App for Containers

Access diagnostic logs

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

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

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

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:

az webapp log tail --name <app-name> --resource-group <resource-group-name>

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.chinacloudsites.cn/api/logs/docker.

Configure multi-container apps

• Use persistent storage in Docker Compose
• Preview limitations
• Docker Compose options

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 Azure CLI.

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings WEBSITES_ENABLE_APP_SERVICE_STORAGE=TRUE

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:

wordpress:
  image: <image name:tag>
  volumes:
  - "${WEBAPP_STORAGE_HOME}/site/wwwroot:/var/www/html"
  - "${WEBAPP_STORAGE_HOME}/phpmyadmin:/var/www/phpmyadmin"
  - "${WEBAPP_STORAGE_HOME}/LogFiles:/var/log"

Preview limitations

Multi-container is currently in preview. The following App Service platform features aren't supported:

• Authentication / Authorization
• Managed Identities
• CORS
• Virtual network integration isn't supported for Docker Compose scenarios
• Docker Compose on Azure App Services currently has a limit of 4,000 characters at this time.

Docker Compose options

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

Supported options

• command
• entrypoint
• environment
• image
• ports
• restart
• services
• volumes (mapping to Azure Storage is unsupported)

Unsupported options

• build (not allowed)
• depends_on (ignored)
• networks (ignored)
• secrets (ignored)
• ports other than 80 and 8080 (ignored)
• default environment variables like $variable and ${variable} unlike in docker

Syntax Limitations

• "version x.x" always needs to be the first YAML statement in the file
• ports section must use quoted numbers
• image > volume section must be quoted and can't have permissions definitions
• volumes section must not have an empty curly brace after the volume name

robots933456 in logs

You may see the following message in the container logs:

2019-04-08T14:07:56.641002476Z "-" - - [08/Apr/2019:14:07:56 +0000] "GET /robots933456.txt HTTP/1.1" 404 415 "-" "-"

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.