Damir's Corner.

Continuous Deployment of a DocPad Site to an Azure Web App Using Git

Azure Deployment Script for Building the Site

In the scope of changing my blogging platform I also decided to switch from self-hosting the blog to hosting it in a Microsoft Azure web app. One of the available features, I want to take advantage of, is continuous deployment from a Git repository at one of the supported repository sites. Of course, the repository only contains the sources for the site, therefore it will need to be built every time the latest version is retrieved from the repository.

Configuration of the build that happens on every deployment will need to be committed to the repository along with the rest of the site. It turns out, azure-cli can generate most of it. Once this npm package is globally installed, it can be instructed to create a generic deployment script for a Node.js project:

npm install azure-cli -g
azure site deploymentscript --node

The generated deploy.cmd script ensures a working Node.js environment but doesn't know anything about DocPad and how to compile a site using it. Fortunately the script is well commented and easy to extend. There are several sections in the script, building the site will belong at the end of Deployment section. By default it consists of three parts, DocPad build will be the forth one, added immediately after the installation of npm packages:

:: 4. Build DocPad Site
echo Building the DocPad site
pushd %DEPLOYMENT_TARGET%
call  %DEPLOYMENT_TARGET%\node_modules\.bin\docpad.cmd generate --env static
IF !ERRORLEVEL! NEQ 0 goto error

There's one more change required to ensure reliable building in Azure. On first use DocPad prompts you to agree with the terms of use. This needs to be disabled or the Azure build will fail when this happens. The configuration setting can be added at the beginning of docpad.coffee file:

docpadConfig =
  prompts: false

Once you commit all three files to the repository (.deployment, deploy.cmd and docpad.coffee), everything is ready for Azure deployment.

Configuring Continuous Deployment in Azure

All of the Azure configuration will be done using the Azure preview portal. You first need to provision a new web app to host your site.

If you're new to Microsoft Azure, pay attention to the service plan you're going to choose. While you're just testing everything during development, you'll want to take advantage of the free shared infrastructure tier, which allows you to host up to 10 sites for free.

Once the web app is providioned for you, you can configure continuous deployment in its dashboard by clicking on the corresponding tile.

The wizard will guide you through the following steps:

• Choose Source (e.g. Bitbucket or GitHub)
• Authorization (using OAuth to avoid enetering password into Azure portal)
• Choose your organization (containing the repository you want to use)
• Choose project (i.e. repository to use)
• Choose branch (master by default, I have a dedicated deploy branch for deployment)

Once you configure everything, Azure will scan the repository and start the deployment of the latest commit in the selected branch. If everything goes well, the build will succeed and the site will be deployed.

If you try to navigate to your site, it still won't work, because DocPad generated the site in out subfolder of the working directory, while by default the root directory is being served. To change that navigate to Settings > Application settings and scroll to the bottom of the pane. Virtual applications and directories are configured there. Delete the existing root entry pointing at site\wwwroot and create a new one pointing at site\wwwroot\out. After you save the changes, the site should start working as expected.

Troubleshooting Azure Web App Deployment

If it still doesn't work for you, you'll want to access the files on the server to diagnose the issue. There are 2 ways to do that.

You can use Server Explorer in Visual Studio. If you're connecting to Azure for the first time, you'll need to right click on the Azure node and select Connect to Microsoft Azure Subscription... from the context menu. After you enter your Azure credentials, you'll be able to navigate to your web app and directly access any of the files.

Alternatively you can connect to the web app host using FTP. I don't think the password is displayed anywhere in the portal, but you can get all the connection details by downloading the publish profile from the web app dashboard.

The downloaded XML file contains two publish profiles; you need the one with FTP as publishMethod. The attributes of interest are: publishUrl, userName and userPWD. Enter this information into your FTP client of choice to access the files.