Deploying PHP 8.0 applications with Azure App Service

To be able to run PHP applications on Azure App Services which are using PHP 8.0 features, the Runtime Stack has to be changed. With the newer Runtime Stack, you also have to update the nginx.conf of the underlying Docker image. This article describes how you can achieve that.

Since summer 2020, Azure provides PHP 8.0 as Runtime Stack for Azure App Services.

With the PHP 8.0 Runtime Stack, the underlying Docker image has also changed the webserver in use from Apache to nginx.

Modern PHP applications like Laravel are making heavily use of Apache’s mod_rewrite features. If you have to upgrade to PHP 8 on Azure App Service you can no longer use the standard .htaccess file: nginx has no support for something like .htaccess files. Instead, you have to adjust the configuration files of nginx.

Azure App Service’s PHP 8.0 Runtime Stack uses the nginx/php-fpm Docker image. Based upon it, the configuration file /etc/nginx/sites-available/default inside the Docker container must be updated.

App Services provides two ways to customize the deployment and environment:

1. When the Docker container starts, you can run your own startup script or command.
2. During a deployment of an application, Kudu looks for a .deployment file inside the repository to be deployed. You can use your own commands to customize the deployment.

Adjusting the nginx configuration with help of Kudu is not possible: The Kudu job has no access to the Docker runtime environment. Neither the filesystem with /etc/nginx/sites-available/default is available, nor can the nginx service be restarted.

Instead, you have to use the Startup Command option in your App Service > Configuration > General settings page:

The startup command is executed as soon as the Docker container had been started. It can either be a number of commands separated by semicolons or a custom shell script in your Git repository.

Please note, that you have to use /home/site/repository/${YOUR_SCRIPT} and not /home/site/wwwroot/${YOUR_SCRIPT}. When the startup script is executed, Kudu has not deployed the application yet. Your startup script can not be found and the Docker container fails to start.

Custom startup script for the PHP 8.0 Runtime Stack

The custom startup script is trivial: It just replaces nginx’ default site configuration with a custom nginx.conf from your Git repository:

#!/bin/bash
echo "Replacing nginx configuration for serving PHP 8.0-based applications"
cp /home/site/repository/deployment/azure-app-service/nginx.conf /etc/nginx/sites-available/default

echo "Reloading nginx to apply new configuration"
service nginx reload

The deployment/azure-app-service/nginx.conf is based upon the sites-available/default configuration and contains the required adjustments for Laravel apps.