Azure App Service on Linux FAQ

With the release of App Service on Linux, we're working on adding features and making improvements to our platform. This article provides answers to questions that our customers have been asking us recently.

If you have a question, comment on this article.

Built-in images

I want to fork the built-in Docker containers that the platform provides. Where can I find those files?

You can find all Docker files on GitHub.

What are the expected values for the Startup File section when I configure the runtime stack?

Stack Expected Value
Java SE the command to start your JAR app (for example, java -jar /home/site/wwwroot/app.jar --server.port=80)
Tomcat the location of a script to perform any necessary configurations (for example, /home/site/deployments/tools/startup_script.sh)
Node.js the PM2 configuration file or your script file
.NET Core the compiled DLL name as dotnet <myapp>.dll
PHP optional custom startup
Python optional startup script
Ruby the Ruby script that you want to initialize your app with

These commands or scripts are executed after the built-in Docker container is started, but before your application code is started.

Management

What happens when I press the restart button in the Azure portal?

This action is the same as a Docker restart.

Can I use Secure Shell (SSH) to connect to the app container virtual machine (VM)?

Yes, you can do that through the source control management (SCM) site.

Note

You can also connect to the app container directly from your local development machine using SSH, SFTP, or Visual Studio Code (for live debugging Node.js apps). For more information, see Remote debugging and SSH in App Service on Linux.

How can I create a Linux App Service plan through an SDK or an Azure Resource Manager template?

Set the reserved field of the app service to true.

Continuous integration and deployment

My web app still uses an old Docker container image after I've updated the image on Docker Hub. Do you support continuous integration and deployment of custom containers?

Yes, to set up continuous integration/deployment for Azure Container Registry or DockerHub, by following Continuous Deployment with Web App for Containers. For private registries, you can refresh the container by stopping and then starting your web app. Or you can change or add a dummy application setting to force a refresh of your container.

Do you support staging environments?

Yes.

Can I use 'WebDeploy/MSDeploy' to deploy my web app?

Yes, you need to set an app setting called WEBSITE_WEBDEPLOY_USE_SCM to false.

Git deployment of my application fails when using Linux web app. How can I work around the issue?

If Git deployment fails to your Linux web app, choose one of the following options to deploy your application code:

  • Use the Continuous Delivery (Preview) feature: You can store your app's source code in an Azure DevOps Git repo or GitHub repo to use Azure Continuous Delivery. For more information, see How to configure Continuous Delivery for Linux web app.

  • Use the ZIP deploy API: To use this API, SSH into your web app and go to the folder where you want to deploy your code. Run the following code:

    curl -X POST -u <user> --data-binary @<zipfile> https://{your-sitename}.scm.azurewebsites.net/api/zipdeploy
    

    If you get an error that the curl command is not found, make sure you install curl by using apt-get install curl before you run the previous curl command.

Language support

I want to use web sockets in my Node.js application, any special settings, or configurations to set?

Yes, disable perMessageDeflate in your server-side Node.js code. For example, if you are using socket.io, use the following code:

const io = require('socket.io')(server,{
  perMessageDeflate :false
});

Do you support uncompiled .NET Core apps?

Yes.

Do you support Composer as a dependency manager for PHP apps?

Yes, during a Git deployment, Kudu should detect that you're deploying a PHP application (thanks to the presence of a composer.lock file), and Kudu will then trigger a composer install.

Custom containers

Can I use Managed Identities with App Service when pulling images form ACR?

Yes, this functionality is available from the Azure CLI. You can use system-assigned or user-assigned identities. This functionality isn't currently supported in the Azure portal.

I'm using my own custom container. I want the platform to mount an SMB share to the `/home/` directory.

If WEBSITES_ENABLE_APP_SERVICE_STORAGE setting is unspecified or set to false, the /home/ directory will not be shared across scale instances, and files written will not persist across restarts. Explicitly setting WEBSITES_ENABLE_APP_SERVICE_STORAGE to true will enable the mount. Once this is set to true, if you wish to disable the mount, you need to explicitly set WEBSITES_ENABLE_APP_SERVICE_STORAGE to false.

My container fails to start with "no space left on device". What does this error mean?

App Service on Linux uses two different types of storage:

  • File system storage: The file system storage is included in the App Service plan quota. It's used when files are saved to the persistent storage that's rooted in the /home directory.
  • Host disk space: The host disk space is used to store container images. It's managed by the platform through the docker storage driver.

The host disk space is separate from the file system storage quota. It's not expandable and there is a 15 GB limit for each instance. It's used to store any custom images on the worker. You might be able to use larger than 15 GBs depending on the exact availability of host disk space, but this isn't guaranteed.

If the container's writable layer saves data outside of the /home directory or a mounted azure storage path, the host disk space will also be consumed.

The platform routinely cleans the host disk space to remove unused containers. If the container writes a large quantity of data outside of the /home directory or Bring Your Own Storage (BYOS), it will result in startup failures or runtime exceptions once the host disk space limit is exceeded.

We recommend that you keep your container images as small as possible and write data to the persistent storage or BYOS when running on Linux App Service. If not possible, you have to split the App Service plan because the host disk space is fixed and shared between all containers in the App Service Plan.

My custom container takes a long time to start, and the platform restarts the container before it finishes starting up.

You can configure the amount of time the platform will wait before it restarts your container. To do so, set the WEBSITES_CONTAINER_START_TIME_LIMIT app setting to the value you want. The default value is 230 seconds, and the maximum value is 1800 seconds.

What is the format for the private registry server URL?

Provide the full registry URL, including http:// or https://.

What is the format for the image name in the private registry option?

Add the full image name, including the private registry URL (for example, myacr.azurecr.io/dotnet:latest). Image names that use a custom port cannot be entered through the portal. To set docker-custom-image-name, use the az command-line tool.

Can I expose more than one port on my custom container image?

We don't support exposing more than one port.

Can I bring my own storage?

Yes, bring your own storage is in preview.

Why can't I browse my custom container's file system or running processes from the SCM site?

The SCM site runs in a separate container. You can't check the file system or running processes of the app container.

Do I need to implement HTTPS in my custom container?

No, the platform handles HTTPS termination at the shared front ends.

Do I need to use WEBSITES_PORT for custom containers?

Yes, this is required for custom containers. To manually configure a custom port, use the EXPOSE instruction in the Dockerfile and the app setting, WEBSITES_PORT, with a port value to bind on the container.

Can I use ASPNETCORE_URLS in the Docker image?

Yes, overwrite the environmental variable before .NET core app starts. E.g. In the init.sh script: export ASPNETCORE_URLS={Your value}

Multi-container with Docker Compose

How do I configure Azure Container Registry (ACR) to use with multi-container?

In order to use ACR with multi-container, all container images need to be hosted on the same ACR registry server. Once they are on the same registry server, you will need to create application settings and then update the Docker Compose configuration file to include the ACR image name.

Create the following application settings:

  • DOCKER_REGISTRY_SERVER_USERNAME
  • DOCKER_REGISTRY_SERVER_URL (full URL, ex: https://<server-name>.azurecr.io)
  • DOCKER_REGISTRY_SERVER_PASSWORD (enable admin access in ACR settings)

Within the configuration file, reference your ACR image like the following example:

image: <server-name>.azurecr.io/<image-name>:<tag>

How do I know which container is internet accessible?

  • Only one container can be open for access
  • Only port 80 and 8080 is accessible (exposed ports)

Here are the rules for determining which container is accessible - in the order of precedence:

  • Application setting WEBSITES_WEB_CONTAINER_NAME set to the container name
  • The first container to define port 80 or 8080
  • If neither of the above is true, the first container defined in the file will be accessible (exposed)

How do I use depends_on?

The depends_on option is unsupported on App Service and it'll be ignored. Just as the control startup and shutdown recommendation from Docker, App Service Multi-container apps should check dependencies through application code - both at startup and disconnection. The example code below shows a Python app checking to see if a Redis container is running.

import time
import redis
from flask import Flask
app = Flask(__name__)
cache = redis.Redis(host='redis', port=6379)
def get_hit_count():
    retries = 5
    while True:
        try:
            return cache.incr('hits')
        except redis.exceptions.ConnectionError as exc:
            if retries == 0:
                raise exc
            retries -= 1
            time.sleep(0.5)
@app.route('/')
def hello():
    count = get_hit_count()
    return 'Hello from Azure App Service team! I have been seen {} times.\n'.format(count)
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=80, debug=True)

Web Sockets

Web Sockets are supported on Linux apps.

Important

Web Sockets are now supported for Linux apps on Free App Service plans. We support up to five web socket connections on Free App Service plans.

Pricing and SLA

What is the pricing, now that the service is generally available?

Pricing varies by SKU and region but you can see more details at our pricing page: App Service Pricing.

Other questions

How does the container warmup request work?

When Azure App Services starts your container, the warmup request sends an HTTP request to the /robots933456.txt endpoint of your application. This is simply a dummy endpoint, but your application needs to reply with any non-5XX status code. If your application logic doesn't reply with any HTTP status code to nonexistent endpoints, the warmup request can't receive a response and it perpetually restarts your container. The warmup request also might fail due to port misconfiguration.

To ensure that the port is correctly configured on Azure App Services, see the question How do I specify port in my Linux container?

Is it possible to increase the container warmup request timeout?

The warmup request by default fails after waiting 240 seconds for a reply from the container. You may increase the container warmup request timeout by adding the application setting WEBSITES_CONTAINER_START_TIME_LIMIT with a value between 240 and 1800 seconds.

How do I specify port in my Linux container?

Container type Description How to set/use port
Built-in containers If you select a language/framework version for a Linux app, a predefined container is selected for you. To point your app code to the right port, use the PORT environment variable.
Custom containers You have full control over the container. App Service has no control about which port your container listens on. What it does need is to know which port to forward requests to. If your container listens to port 80 or 8080, App Service is able to automatically detect it. If it listens to any other port, you need to set the WEBSITES_PORT app setting to the port number, and App Service forwards requests to that port in the container. The WEBSITES_PORT app setting does not have any effect within the container, and you can’t access it as an environment variable within the container.

Can I use a file based database (like SQLite) with my Linux Webapp?

The file system of your application is a mounted network share. This enables scale out scenarios where your code needs to be executed across multiple hosts. Unfortunately this blocks the use of file-based database providers like SQLite since it's not possible to acquire exclusive locks on the database file. We recommend a managed database service: Azure SQL, Azure Database for MySQL or Azure Database for PostgreSQL

What are the supported characters in application settings names?

You can use only letters (A-Z, a-z), numbers (0-9), and the underscore character (_) for application settings.

Where can I request new features?

You can submit your idea at the Web Apps feedback forum. Add "[Linux]" to the title of your idea.