WordPress on Web app for Containers

7 minute read • April 16, 2017

Web Apps on Linux allows running web apps natively on Linux. WordPress is popular blogging platform primarily used on Linux distributions.  Today we have released WordPress for App Service on Linux in the Azure marketplace that helps you quickly create a WordPress application on Web apps (Linux) . This docker image enables you to run a WordPress site on Azure Web App on Linux  using either :
    1. Azure Database for MySQL : It is a Microsoft solution for MySQL service on Azure that provides a managed database service for app development and deployment that allows you to stand up a MySQL database in minutes and scale on the fly .
    2. Local Database  : You can manually setup your web app to use Local database. This option is not provided from Azure portal for WordPress on Linux template.

Before you begin

If you don't have an Azure subscription, create a free account before you begin.

Deploy from Marketplace

Log in to the Azure portal.Click here to create the WordPress application.wordpress-linux
Name Description
App Name
Enter a unique app name for your **Web App Name**. This name is used as part of the default DNS name for your app <app_name>.azurewebsites.net, so it needs to be unique across all apps in Azure. You can later map a custom domain name to your app before you expose it to your users
Subscription Select a Subscription. If you have multiple subscriptions, choose the appropriate subscription.
Resource group
Enter a resource group. A resource group is a logical container into which Azure resources like web apps, databases that is deployed and managed. You can create a resource group or use an existing one
App Service Plan
App Service plans represent the collection of physical resources used to host your apps. Select the Location and the Pricing tier. For more information on pricing, see App service pricing tier 
Database Provider Use Azure Database for MySQL for database solution
This will deploy a WordPress custom image on to Web Apps on Linux . Note there might be cold start for the first request to the site created.

Using GIT repo for WordPress code

Version 0.3 pulls wordpress code from our GIT repo when you create a when app using this Docker image .  If you have custom code on Github as well , you can edit GIT_REPO after the app is created and GIT_BRANCH values in app settings.
  1. Create a Web App for Containers
  2. Add new App Settings
Name Default Value
GIT_REPO https://github.com/azureappserviceoss/wordpress-azure
GIT_BRANCH linux_appservice
  1. Browse your site
Note: GIT directory: /home/site/wwwroot. When you deploy it first time, Sometimes need to check wp-config.php. RM it and re-config DB information is necessary. Before restart web app, need to store your changes by "git push", it will be pulled again after restart.

How to configure to use Local Database with web app

  1. Create a Web App for Containers
  2. Update App Setting WEBSITES_ENABLE_APP_SERVICE_STORAGE = true (If you like to keep you DB after restart.)
  3. Add new App Settings
Name Default Value
Note: We create a database "azurelocaldb" when using local mysql . Hence use this name when setting up the app
  1. Browse your site
  2. Complete WordPress install
Note: Do not use the app setting DATABASE_TYPE=local if using Azure database for MySQL

How to update WordPress core , theme or plugins

If WEBSITES_ENABLE_APP_SERVICE_STORAGE= false  ( which is the default setting ) , we recommend you DO NOT update the WordPress core version , themes or files from WordPress admin dashboard. 
There is a trade off between file server stability and file persistence . Choose either one option to updated your files :
Since we are using local storage for better stability for the web app , you will not get file persistence.  In this case , we recommend to follow these steps to update WordPress Core  or a theme or a Plugins version :
  1. Fork the repo https://github.com/azureappserviceoss/wordpress-azure
  2. Clone your repo locally and make sure to use ONLY linux-appservice branch 
  3. Download the latest version of WordPress , plugin or theme being used locally 
  4. Commit the latest version bits into local folder of your cloned repo 
  5. Push your changes to the your forked repo 
  6. Login to Azure portal and select your web app 
  7. Click on Application Settings -> App Settings and change GIT_REPO to use your repository from step #1. If you have changed the branch name , you can continue to use linux-apservice . If you wish to use a different branch , update GIT_BRANCH setting as well. 
OPTION 2 :  You can update WEBSITES_ENABLE_APP_SERVICE_STORAGE =true  to enable app service storage to have file persistence . Note when there are issues with storage  due to networking or when app service platform is being updated , your app can be impacted . 

How to turn on Xdebug

  1. By default Xdebug is turned off as turning it on impacts performance.
  2. Connect by SSH.
  3. Go to /usr/local/php/etc/conf.d, Update xdebug.ini as wish, don't modify the path of below line.zend_extension=/usr/local/php/lib/php/extensions/no-debug-non-zts-20170718/xdebug.so
  4. Save xdebug.ini, Restart apache by below cmd: apachectl restart
  5. Xdebug is turned on.


  • Some unexpected issues may happen after you scale out your site to multiple instances, if you deploy a WordPress site on Azure with this docker image and use the MariaDB built in this docker image as the database.
  • The phpMyAdmin built in this docker image is available only when you use the MariaDB built in this docker image as the database.
  • Please Include App Setting WEBSITES_ENABLE_APP_SERVICE_STORAGE = true when use built in MariaDB since we need files to be persisted.

Change Log

  • Version 0.3
    1. Use Git to deploy wordpress.
    2. Update version of PHP/Apache/Mariadb/Phpmyadmin.
    3. Add Xdebug extenstion of PHP.
    4. Use supervisord to keep SSHD and Apache.
    5. This is NOT compatible with tag 0.2 and tag 0.1 for Docker image wordpress-alpine-php

Migrating an existing WordPress site

This image creates a new WordPress application every time it is deployed. If you are migrating your application to this site , please follow directions to export and import as mentioned on Wordpress Codex. If you have a complex WordPress application where the above mentioned export and import options are not effective, Web Apps on Linux supports git deployment and you use FTP  or GIT deployment to replace the file system on the site created with this template to bring your own content. You can use PHPmyadmin available with this solution to import your application database content.


The docker image has been updated from this  docker image  to using a new format where the docker image only contains the server components. The application code for WordPress is deployed via GIT from  github repo .

Update your application to use the new image appsvc/apps:apache-php-mysql-0.1

  • If you have an existing application created using the WordPress image , check the Application setting to verfiy which image is being used with DOCKER_CUSTOM_IMAGE setting .
  • If the setting value is apache-php-mysql-0.1 , no changes needed .
  • If the value is wordpress-0.2 or wordpress-0.1 or wordpress  and  follow the steps below based on the database being used :
    • Azure Database for MySQL
      • Create a new web app with WordPress  from the Azure marketplace.
      • Select "Existing resource group"  and choose the resource group in which your Azure Database for MySQL  database exists.
      • Select the same app service plan in which the current site assigned to.
      • If using Azure Database for MySQL   , select your existing database that is being used by your web app.   Test the new site to make sure it is working as expected before deleting the older app.
    • Local database
      • Backup your web app and database manually.
      • Create a new web app with WordPress  from the Azure marketplace and choose Azure database for MySQL
      • Migrate your database to the new database and your files to newly created web app.
      • Note : There is bug with Local database causing the application to break once the app is  provisioned which will be fixed in early August 2017 . If you wish to use Local database , wait until Local database is support for WordPress template next month.
Using App  Service Storage If you using a web app that was created from Azure marketplace for Web App on Linux using WordPress , Drupal , Mediawiki and  Joomla  , please add the following app setting WEBSITES_ENABLE_APP_SERVICE_STORAGE app setting to true to continue using App service Storage  (platform SMB share i.e /home/ folder ) . Use the platform file storage in these  two scenarios :
  1. When you scale out using the autoscale feature in Web app for Linux. 
  2. If your application modifies the the files system and you need this new changes to the file system to be persistent . For example , with a WordPress app if you install a plugin , Wordpress adds a few files to the files system for the plugin and modifies the database. If you scale up or the instance your app is running on is recycled you will loose the plugin files which can break your production application.   Hence in such cases it is recommended to set the app setting to true. 
NOTE: If the setting is not set to true  the changes to the file system are not persisted.