How to deploy OctoberCMS on Azure

Lawrence Muthoga
Mar 8, 2018 · 8 min read

Hi there, If you’re like me, you’ve probably tried deploying your favorite tool across multiple platforms to varying degrees of success. I love OctoberCMS and Azure is one of those platforms that it should be easy and fun to deploy to, right?

WRONG — At least till now.

Back then you had to launch a Virtual Machine, Install your LAMP server ( Ubuntu FTW! ) and fire up your October Instance. This ofcourse can lead to issues of scalability when you’re looking to service millions of requests. Hence the question, what if I wanted to blow this up? What If i wanted to autoscale at will, expand my service across regions and countries? What if I wanted to do that easily? The answer is clear — PAAS

For those of you new to OctoberCMS, Its a Laravel based CMS that is super developer-friendly and pretty easy to work with. You can check it out here:

Azure is Microsoft’s cloud hosting platform that spans over a huge number of services both Closed and Open Source. The embracing of open-source has led to a great many scenarios that one would have thought impossible in Microsoft’s cloud but now opens a whole new set of possibilities. ( )

A little disambiguation:

This article will only look at using PAAS solutions on Azure to run OctoberCMS.

There are multiple ways to achieve what will be shown but I’ll be taking the easiest route and cover some WTFs that you can expect.

You can use Virtual Machines to run OctoberCMS but where’s the fun in that?


Before we begin, we’ll need a few things:

  1. A working knowledge of how to install OctoberCMS ( find a short guide here: )
  2. An Azure account. You can create a trial account here: Azure Trial. If you are a student and don’t have a credit card, you can use your student credentials to get an account here: Azure for Students
  3. A good sense of humor.

Step 1 : The Database:

For this walkthrough I’ll use MySQL running as a service on Azure.

There is great documentation on how to do this on the official Microsoft documentation: ( ) if you want to get deeper documentation

I’ll be following the same steps but adding a few changes to cover some WTFs that I encountered

Go to the Azure Portal, go to create a resource and search for MySQL:

I’ll be using the PAAS Azure Database for MyQSL provided by Microsoft. This is a database server meaning I can add multiple databases as I move along.

Select it and hit create.

Enter the details and choose a pricing tier that works for you.

Pricing Tiers: For this one I’ll be using a basic tier. You can scale up and down as you wish. Prices will vary depending on region and features chosen.

Once you’ve selected your database and pricing tier, hit create and watch the magic happen. Azure will inform you once the deployment is done. If you go to your database page, it should look something like this:

We shall now create a table in the database. You can connect this database server to your MySQL management software.

If you’re comfortable with the console, you can use the azure console found on the top bar here:

This will open the azure terminal on the window and you can use this to create your table.

mysql --host <fully qualified server name> --user <server admin login name>@<server name> -p

The details are on the overview page .

You’ve probably figured out by now that you need to allow access from specific IPs to the database. If not, you will receive an error that reads:

To sort this out, head to the Connection Security tab and add your IP or a range of IPs to allow connection. In my demo I’ll allow all IPs ( THIS IS NOT RECOMMENDED!! for obvious reasons ). Don’t forget to save.

With that done, you can reconnect and create your database.

If you’re on the Cloud Shell:

mysql --host <fully qualified server name> --user <server admin login name>@<server name> -p

Enter your password and create your database:

create database <database name>;

This creates the database that we shall use for our OctoberCMS deployment

Step 2: OctoberCMS

There are two ways to getting your OctoberCMS site onto Azure. You can use source control and link it to your site .

For my scenario, I’ll be cloning from the official OctoberCMS installer git repo found here:

Since this is PAAS we’re going to use Azure App Services. Let’s jump into it:

Creating the Empty PHP app:

Head back to the dashboard and under App Services, click add and search for PHP. Select PHP empty web app and hit create.

Enter the details, select a pricing tier that works for you and hit create. It should be ready in less than a minute. It is recommended that you put it in the same resource group and region as your database as this allows for them to be close both in region and latency

Once complete, you should have an overview page and a link to your new web app:

What you now need to do is add the installer to the site. Azure allows you to use continous delivery if you have a repo you constantly pull from. TO add your repo, we first need to remove the default repo and add ours. You do this by heading to Deployment Options and removing the existing one

Then click on setup and select external repository. If you have forked the octobercms installer into your account, you can fetch it there. Since it is external to our account, we’ll access it as such. the link is:

Hit OK and go back to deployment options. Azure will be fetching the repository. YOu can manually sync if it hasn’t started. Once complete, It will look something like this:

You can test if this has worked by going to your link and appending install.php:

https://< your website name >

Since OctoberCMS requires PHP 7.0 and above to work, we need to change our PHP version. This is done by going to Application Settings and changing the PHP version to 7.0 or above. Don’t forget to turn on web sockets as October uses sockets during the installation process. This will save you the agony of database errors later

UPDATE: PHP 7.1. works with the least issues

As always, don’t forget to save.

Adding Composer:

Before we get too far, we also need to add composer to the project. This is done by going to site extensions, selecting add:

And Adding composer:

Once that is installed, you can then go back to your installation page.

Your installation should now be ready:

For your database, use the credentials you created in the databse section above:

As we didn’t turn off SSL in our database, we’ll get the error:

Connection failed: SQLSTATE[HY000] [9002] SSL connection is required. Please specify SSL options and retry.

To fix this, head to your database settings and turn off SSL:

Retry and it should work:


Step 3: Web.Config

Azure runs its web apps on IIS and this leads to a few issues like broken links. The use of the composer plugin also slightly messes with nested vendor files leading to backend pages not working.:

The fix to this is simple. Add a web.config file with a clear tag before the rules. You can find it here:

To add it, go to the app service editor, click go and add a web.config file tjo the root of the application:

Add the web.config:

This fixes it to this:

Sign in and you’re all good to go!!!!

If you have made it this far, your OctoberCMS instance should be all nice and ready to go!

You also deserve a cookie, so here’s one:


Lawrence Muthoga

Written by

I can’t remember who I stole my bio from or why

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade