Running Orchard on AppHarbor

Introduction

We have had quite a few users try to run Orchard CMS on AppHarbor with varying levels of success. This is a guide on how to configure what is hopefully a reasonably dependable setup using Amazon S3 for file-persistence.

First, it's important to note that the source-control-based AppHarbor deployment model is not currently optimized for maintaining sites based on a traditional CMS. The AppHarbor platform assumes that all application configuration and behaviour (i.e. how the application looks and works) is encoded in the code pushed to the platform, and that any updates are made through revision control commits. Application run-time state, on the other hand, is expected to be persisted other places than the local web server filesystem (i.e. in a database or storage service like Amazon S3).

A typical CMS doesn't work like this. Installation typically works by putting a bunch of files on a web server before running a web-based installation script that causes the CMS to unpack itself on the web server. While text content may be stored in some sort of SQL-based database, media-files like images are often stored on the filesystem. Additional application behaviour is typically added using modules installed directly on the file system of the web server. Application appearance is often modified using build-in editors, directly changing style sheets and layout-files on the web server.

This model does not work well on AppHarbor because the platform does not concern itself with local filesystem changes introduced by an application after it is deployed. Any local filesystem changes will be lost if the application is redeployed and run-time changes will not be synced if the application is deployed to multiple web servers.

We can work around the worst of these limitations by using Amazon S3 to persist media-files and by adopting a workflow where modules and themes are installed locally before changes are pushed to AppHarbor. This guide describes how to set up Orchard, but should be broadly applicable for running other CMS's on AppHarbor.

Installing Orchard Locally

1. Get Microsoft's Web Platform Installer
2. Use Web Platform Installer to install Orchard and its various dependencies
3. Open WebMatrix and create a new ("from Web Gallery") Orchard site
4. Open the local site in your browser, you should be greeted by the Orchard "Get Started" wizard.
5. Configure Orchard to use "built-in storage (SQL Server CE)" and complete the wizard
   

Configure AppHarbor Application

1. Go to AppHarbor and create a new application
2. Disable precompilation in application settings (several users have reported precompilation not working with Orchard)
3. Create a SQL Server database for the application
4. Use WebMatrix to migrate the SQL Server CE database to your AppHarbor database (you should theoretically be able to install Orchard on your local machine using the remote AppHarbor database, but this approach is not known to work)

The Web Matrix interface should now show your application running locally using the remote AppHarbor database.

Installing the Orchard S3 Storage Provider

1. Download the provider to your local drive
2. Go to the Orchard dashboard on your local installation
3. Under "Modules", select the "Installed" tab and the "Install a module from your computer"
4. Install the module file you just downloaded

Create and Configure S3 Bucket

1. Create an account with Amazon Web Services, if you don't already have one
2. Create an S3 bucket to hold media files for your site
3. Go to the Orchard dashboard - > Settings -> Amazon S3 and input the bucket connection information
4. Upload a media item (a picture or similar) and confirm that it gets placed in the bucket

Push Application to AppHarbor

1. Find the file system location of your WebMatrix site (eg. C:\Users\username\Documents\My Web Sites\Orchard CMS)
2. Initialize a repository with the directory contents using your favourite AppHarbor-supported versioning control system
3. Make sure the Settings.txt (in .\App_Data\Sites\Default\) file is treated as a binary file. This is done with Git by adding Settings.txt -crlf -diff -merge to the .gitattributes file. You need to do this because the settings file uses line-breaks for delimiting individual settings and the line-breaks may be modified by the versioning control system. (on a site note, it's slightly ironic that a thoroughly engineered piece of software like Orchard trips up because it uses a whitespace-sensitive file format for its configuration)
4. Push the repository to AppHarbor for deployment
5. Make sure the site works correctly on AppHarbor

Development workflow

Going forward with an Orchard installation configured using this guide, module- and theme installation should always happen on your local machine, before changes are pushed to AppHarbor. You should not enable full file system write in your AppHarbor application settings. Not having this facility will prevent you from introducing non-durable changes to the application while it's running on AppHarbor. You are generally OK to add content and media to the application while it's running on AppHarbor, as long as you make sure it's persisted either to SQL Server or to the S3 bucket.

Note that your local WebMatrix hosted Orchard will be running of the production AppHarbor SQL Server database and S3 bucket. You might want to use a different database and bucket for adding test-content locally.