21/12/2024, 10:33 Configure a custom container - Azure App Service | Microsoft Learn

Configure a custom container for Azure

App Service
Article • 10/25/2023

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

Change the Docker image of a custom

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

Azure CLI

az webapp config container set --name <app-name> --resource-group

<group-name> --docker-custom-image-name <docker-hub-repo>/<image>

Use an image from a private registry

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

Azure CLI

az webapp config container set --name <app-name> --resource-group

<group-name> --docker-custom-image-name <image-name> --docker-reg‐
istry-server-url <private-repo-url> --docker-registry-server-user
<username> --docker-registry-server-password <password>

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

https://learn.microsoft.com/en-us/azure/app-service/configure-custom-container?tabs=debian&pivots=container-linux 1/13
21/12/2024, 10:33 Configure a custom container - Azure App Service | Microsoft Learn

Use managed identity to pull image from Azure

Container Registry
Use the following steps to configure your web app to pull from Azure Container Registry
(ACR) using managed identity. The steps use system-assigned managed identity, but
you can use user-assigned managed identity as well.

1. Enable the system-assigned managed identity for the web app by using the az
webapp identity assign command:

Azure CLI

az webapp identity assign --resource-group <group-name> --name

<app-name> --query principalId --output tsv

Replace <app-name> with the name you used in the previous step. The output of
the command (filtered by the --query and --output arguments) is the service
principal ID of the assigned identity.

2. Get the resource ID of your Azure Container Registry:

Azure CLI

az acr show --resource-group <group-name> --name <registry-name>

--query id --output tsv

Replace <registry-name> with the name of your registry. The output of the
command (filtered by the --query and --output arguments) is the resource ID of
the Azure Container Registry.

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

Azure CLI

az role assignment create --assignee <principal-id> --scope <reg‐

istry-resource-id> --role "AcrPull"

Replace the following values:

<principal-id> with the service principal ID from the az webapp identity

assign command

<registry-resource-id> with the ID of your container registry from the az

acr show command

https://learn.microsoft.com/en-us/azure/app-service/configure-custom-container?tabs=debian&pivots=container-linux 2/13
21/12/2024, 10:33 Configure a custom container - Azure App Service | Microsoft Learn

For more information about these permissions, see What is Azure role-based
access control.
4. Configure your app to use the managed identity to pull from Azure Container
Registry.

Azure CLI

az webapp config set --resource-group <group-name> --name <app-

name> --generic-configurations '{"acrUseManagedIdentityCreds":
true}'

Replace the following values:

<app-name> with the name of your web app.

 Tip

If you are using PowerShell console to run the commands, you need to escape
the strings in the --generic-configurations argument in this and the next
step. For example: --generic-configurations
'{\"acrUseManagedIdentityCreds\": true'

5. (Optional) If your app uses a user-assigned managed identity, make sure the
identity is configured on the web app and then set the
acrUserManagedIdentityID property to specify its client ID:

Azure CLI

az identity show --resource-group <group-name> --name <identity-

name> --query clientId --output tsv

Replace the <identity-name> of your user-assigned managed identity and use

the output <client-id> to configure the user-assigned managed identity ID.

Azure CLI

az webapp config set --resource-group <group-name> --name <app-

name> --generic-configurations '{"acrUserManagedIdentityID": "
<client-id>"}'

You're all set, and the web app now uses managed identity to pull from Azure Container
Registry.
https://learn.microsoft.com/en-us/azure/app-service/configure-custom-container?tabs=debian&pivots=container-linux 3/13
21/12/2024, 10:33 Configure a custom container - Azure App Service | Microsoft Learn

Use an image from a network protected

registry
To connect and pull from a registry inside a virtual network or on-premises, your app
must integrate with a virtual network (VNET). VNET integration is also needed for Azure
Container Registry with private endpoint. When your network and DNS resolution is
configured, you enable the routing of the image pull through the virtual network by
configuring the vnetImagePullEnabled site setting:

Azure CLI

az resource update --resource-group <group-name> --name <app-name> --

resource-type "Microsoft.Web/sites" --set properties.vnetImagePullEn‐
abled [true|false]

I don't see the updated container

If you change your Docker container settings to point to a new container, it might 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 are 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 more instances. There are also rare cases where the app instances might
change without a scale operation.

Configure port number

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
https://learn.microsoft.com/en-us/azure/app-service/configure-custom-container?tabs=debian&pivots=container-linux 4/13
21/12/2024, 10:33 Configure a custom container - Azure App Service | Microsoft Learn

Service app. You can set it via the Cloud Shell . In Bash:

Azure CLI

az webapp config appsettings set --resource-group <group-name> --

name <app-name> --settings WEBSITES_PORT=8000

In PowerShell:

Azure PowerShell

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -

AppSettings @{"WEBSITES_PORT"="8000"}

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

Configure environment variables

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

Azure CLI

az webapp config appsettings set --resource-group <group-name> --

name <app-name> --settings DB_HOST="myownserver.mysql.data‐
base.azure.com"

In PowerShell:

Azure PowerShell

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -

AppSettings @{"DB_HOST"="myownserver.mysql.database.azure.com"}

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.

https://learn.microsoft.com/en-us/azure/app-service/configure-custom-container?tabs=debian&pivots=container-linux 5/13
21/12/2024, 10:33 Configure a custom container - Azure App Service | Microsoft Learn

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 /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 Cloud
Shell . In Bash:

Azure CLI

az webapp config appsettings set --resource-group <group-name> --

name <app-name> --settings WEBSITES_ENABLE_APP_SERVICE_STORAGE=true

In PowerShell:

Azure PowerShell

Set-AzWebApp -ResourceGroupName <group-name> -Name <app-name> -

AppSettings @{"WEBSITES_ENABLE_APP_SERVICE_STORAGE"=true}

https://learn.microsoft.com/en-us/azure/app-service/configure-custom-container?tabs=debian&pivots=container-linux 6/13
21/12/2024, 10:33 Configure a custom container - Azure App Service | Microsoft Learn

７ Note

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 is always safely encrypted.

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:

https://learn.microsoft.com/en-us/azure/app-service/configure-custom-container?tabs=debian&pivots=container-linux 7/13
21/12/2024, 10:33 Configure a custom container - Azure App Service | Microsoft Learn

Portmust 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

Bash

#!/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

Dockerfile

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

https://learn.microsoft.com/en-us/azure/app-service/configure-custom-container?tabs=debian&pivots=container-linux 8/13
21/12/2024, 10:33 Configure a custom container - Azure App Service | Microsoft Learn

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:

Azure CLI

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:

Azure CLI

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.

https://learn.microsoft.com/en-us/azure/app-service/configure-custom-container?tabs=debian&pivots=container-linux 9/13
21/12/2024, 10:33 Configure a custom container - Azure App Service | Microsoft Learn

You can also inspect the log files in a browser at https://<app-

name>.scm.azurewebsites.net/api/logs/docker .

Configure multi-container apps

７ Note

Sidecar containers (preview) will succeed multi-container apps in App Service. To

get started, see Tutorial: Configure a sidecar container for custom container in
Azure App Service (preview).

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 Cloud Shell .

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:

YAML

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

https://learn.microsoft.com/en-us/azure/app-service/configure-custom-container?tabs=debian&pivots=container-linux 10/13
21/12/2024, 10:33 Configure a custom container - Azure App Service | Microsoft Learn
- "${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

https://learn.microsoft.com/en-us/azure/app-service/configure-custom-container?tabs=debian&pivots=container-linux 11/13
21/12/2024, 10:33 Configure a custom container - Azure App Service | Microsoft Learn

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

７ 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:

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.

Next steps
Tutorial: Migrate custom software to Azure App Service using a custom container

Tutorial: Configure a sidecar container for custom container in Azure App Service
(preview)

Or, see more resources:

Environment variables and app settings reference
Load certificate in Windows/Linux containers

Feedback
https://learn.microsoft.com/en-us/azure/app-service/configure-custom-container?tabs=debian&pivots=container-linux 12/13
21/12/2024, 10:33 Configure a custom container - Azure App Service | Microsoft Learn

Was this page helpful?  Yes  No

Provide product feedback | Get help at Microsoft Q&A

https://learn.microsoft.com/en-us/azure/app-service/configure-custom-container?tabs=debian&pivots=container-linux 13/13