How to setup Orchard on AppHarbor

Tags: Orchard, AppHarbor

Orchard is an open-source (BSD license) CMS built on ASP.NET MVC 3.

That's really not much of an introduction. This post isn't meant to introduce one to Orchard or even how to use. I'll save those posts for later.

This post is going to be about how to setup Orchard on AppHarbor and get it up and running in minutes. This post was inspired by a post by John Zablocki over at His instructions are pretty easy to follow but I disagreed with his methodology for working with Orchard on AppHarbor slightly and thought I'd show a my approach. Here's the plan.

Before we begin here are the pre-requisites:

That should be it. Why are we working with BitBucket rather than GitHub? Personally, there are lots of reasons but there's one problem GitHub has; no free private repositories. This is a dealbreaker for one very important reason. Orchard, for reasons not clear to me yet, keeps the connection string to the database in a plain-text settings file rather than in the web.config. AppHarbor has a way for you to set the connection string from its web interface but since the Orchard team decided to keep the connection string elsewhere, we're forced to commit the actual connection string of the actual production database along with our code. We obviously can't use the public repositories offered by GitHub in this scenario. Why not use SQL CE and avoid the issue? That's even worse since we'll have no access to our SQL CE database once our code reaches AppHarbor and the entire database will be deleted if another commit is made to our AppHarbor application.

I'll explain the need for the rest of the pre-requisites later on.

Here's the steps you need to follow to get your first application up-and-running on AppHarbor:

1. Create a new application at AppHarbor

Login to your account over at AppHarbor and you should be right at the page where you create a new application. If not, just click the 'Your Applications' link on the top navigation menu.

All you need to do is type in a name in the textbox and click the 'Create New' button. Deleting an application is just as simple so don't spend too much time thinking of a name. You can always rename your application by visiting your application settings later. There isn't even a limit of the number of applications you can create on AppHarbor currently!

2. Go to settings of your application and enable file system write access

Next you'll need to enable file system write access. Orchard has a tendancy for creating files (such as log files) and requires file system write access.

For the most part, you shouldn't depend on the files Orchard creates because AppHarbor will make a clean deploy whenever it gets a new commit. This is the reason you can't use SQL CE over at AppHarbor. 

3. Fork the pre-built binaries of Orchard 1.3.10 repository over at BitBucket

The next step in the process is to fork this mercurial repository or this git repository over at BitBucket.

Once you fork it, you'll be asked for some details. The only requirement is the name field which you should change from the default "Orchard.Web.1.3.10" which is the name of the repository you are forking. Make sure you make it a private repository since you'll be committing some sensitive information to your forked repository.

This repository basically holds the pre-built binaries of Orchard 1.3.10. Orchard has a BSD license and redistribution of the source code and binaries are permitted provided that the license is also added to the distribution, which I've added to the repository. If you'd rather get the binaries direct from the official location, head on over to and click the 'Download as zip (8 mb)' link to the right. I basically downloaded that link, extracted it and pushed it BitBucket as its own repository.

Disclaimer: I only used the mercurial repository while writing this guide. I created the git repo for folks who rather use git rather than mercurial. Everything should work as expected but let me know if it doesn't and I'll test it thoroughly myself.

4. Go to your repository details of your forked project and confirm the following:

  a. The repository is private

You should see a locked golden padlock at your repository's page. If not, click the Admin tab, tick the checkbox labelled 'Private' and then click the 'Save repository details' button.

I can't stress enough how important this is. Due to the nature of Orchard and AppHarbor, I don't see a simple way of setting the connection string via the web.config without modifying the Orchard source and creating your own binaries. Perhaps I'm missing something. If I figure it out, I'll make sure to add it into this post at some point in the future.

  b. Under Access Management, make sure apphb has read access

If you're not already at the 'Admin' tab, go to it and click the 'Access Management' link on the left. It should show a list of users who have access to your repository.

Make sure it only contains you (and other collaborators you'd like to have) and apphb. The user apphb is the BitBucket user for AppHarbor. AppHarbor needs read access to your repository. If apphb is not listed under users, type 'apphb' in the textbox, select the user from the list below (which should have the AppHarbor dragon icon) and then click the 'Read' button.

  c. Under Services, add a POST service that points to your AppHarbor application's build URL

Ok, this just involves copy-pasting some text from AppHarbor to BitBucket and clicking a button but it would help if you got a bit of explanation of what this does. Basically, what going to happen here is that you're going to tell BitBucket to inform AppHarbor of every commit it receives.

To get this wired up, go to your application over at the AppHarbor and click the 'Build URL' button at the left-hand side menu. This will copy the build url to your clipboard.

Then go to BitBucket and click the 'Services' link at the left-hand side menu of the 'Admin' tab. Select the 'POST' service from the 'Select a service...' drop-down menu and click 'Add Service'.

A textbox will appear below where you can enter a url. Paste in the build url you got from AppHarbor and click the 'Save Settings' button. Now you've got your AppHarbor application wired up to your BitBucket repository. Everytime you push a commit to your BitBucket repository, AppHarbor will automatically be informed and automatically pull the changes to your application over at AppHarbor.

5. Clone your bitbucket repository to your local machine

The command used to clone the repository is available in every screenshot of BitBucket above. For mercurial it'll look like `hg clone <repository url>` and for git `git clone <repository url>`. You'll be prompted for a username and/or password when doing so.

6. Start your cloned orchard project using WebMatrix

What is WebMatrix? Wikipedia says, "WebMatrix is a bundle of software running on the developer's machine, with the aim of simplifying the process of web application development using Windows". Basically, think of it as a very, very, very lightweight IDE. You can even develop PHP apps on Microsoft WebMatrix. Anyways, the great thing about WebMatrix is that it will start up your Orchard website for you locally using IIS Express. How do you get a hold of WebMatrix and IIS Express? Microsoft Web Platform Installer. The WPI is a 2mb download which facilitates the installation of a ton of other software of your choosing to your computer. It'll download the software you want, along with any other dependencies, and install them for you. Pretty cool. You can even install Orchard using it. I've actually had some problems with the WPI where it'll fail to install some software due to a bad download and then fail to install it again on retry since it doesn't bother downloading a fresh copy but instead uses a cached copy of the bad download. Hopefully you won't encounter such errors.

Use the WPI to install WebMatrix, IIS Express and the Web Deployment Tool. WebMatrix is going to be your development enviroment, IIS Express your development web server and the Web Deployment Tool is a nice utility for WebMatrix which should have automatically came along with WebMatrix. Basically, it'll setup your website for you on IIS Express.

Once you've installed the above, open up WebMatrix and select the 'Site from Folder'. If the 'Site from Folder' button is unclickable, it probably means you haven't installed some dependency. There should be a tooltip explaining the problem.

7. Run the Orchard setup

After opening up your website on WebMatrix, it should have been automatically started by WebMatrix. You should see a message on the bottom of WebMatrix like the below screenshot (it's going to slide out of view after a few seconds after starting the website).

If you want to learn more about Orchard, you'll probably be spending a lot of time here. The above screenshot shows WebMatrix with the 'Files' section selected in the left-hand side navigation. Click the 'Site' tab which will then show you the URL for your Orchard website.

Go to  the url listed and you should see the Orchard setup page.

Give it a name for your website, your administrator username and password. Make sure to select 'Use an existing SQL Server (or SQL Express) database'. Give it a connection string to a local database. Theoretically, you could give it a connection string to the database we'll create on AppHarbor but I found this slow and prone to timeout exceptions. Whatever you do, don't use SQL Server Compact. Due to the enviroment we'll be hosting our site on (AppHarbor), using SQL CE isn't viable.

Use the default Orchard recipe and click the 'Finish Setup' button to complete the setup. You should arrive at your website's homepage momentarily.

Congratulations, you are now running Orchard on your local machine.

8. Recreate your local Orchard database on a remote AppHarbor hosted database

a. Generate scripts for all the tables the Orchard setup created in your local database

Ok, let's back up a bit. We just completed the Orchard setup on our local machine but our goal is to get Orchard running on AppHarbor. Do we have to go through the setup again? No. We're gonna be pushing all the changes the setup did onto AppHarbor. The only thing we won't be able to push is the database tables Orchard created on setup along with the data it added into those tables. Let's handle that problem now.

Open SQL Management Studio and connect to the server which has the database Orchard used. Generate a script of all the tables Orchard created by rght-clicking the database, clicking the 'Tasks' menu item and then the 'Generate Scripts...' menu item. Follow along the wizard and select every table Orchard created. If this was a empty database before running the Orchard setup, then that would be every table in the database.

Next, you'll need to create a database on AppHarbor, connect to it via SQL Management Studio and execute the script on the AppHarbor database.

b. Create a database on AppHarbor and execute the generated scripts on it

Login to AppHarbor and click 'Add-ons' on the left-hand side navigation menu. This will show a list of add-ons available on AppHarbor. We're going to be using the SQL Server add-on which will give us 20 MB of (shared) SQL Server goodness. Note: we're not using the Dedicated SQL Server add-on which has no free offer. Click the 'See More' link to go to the installation page.

Then click the 'Install' button to install the add-on for this application.

Now SQL Server should be listed in the 'Installed add-ons' list below the 'Build status' section. Click on 'Sql Server' then click the 'Go to SQL Server' link on the add-on page. You should end up on a page showing you your connection string like below (I've obviously changed my connection details).

Use the above details to connect to the AppHarbor database using SQL Management Studio. Once you connect, run the scripts you've generated earlier against it to create the database schema Orchard requires.

9. Use AppHarbor's Sql Server Bulk Copy app to copy your local database data to your AppHarbor database.

Sql Server Bulk Copy is a cool little C# console application developed by AppHarbor used to transfer records from one database to another. Why not just take a backup and restore the database? Because you can't. Well, at least for now. Does that mean you have to backup your data with this tool or have no backups at all? No, AppHarbor does backups for you. But you don't have access to them for now.

Until a more viable solution is found, this seems to be the simplest method of getting access to your data.

We need to use this tool to transfer the initial data Orchard added to your local database to the remote database. It's actually pretty easy here's how you use the app:

AppHarbor.SqlServerBulkCopy.exe --srcusername=dbxx --srcpassword=srcpassword --srcdatabasename=dbxx --dstserver=.\SQLEXPRESSADV --dstusername=dbyy --dstpassword=dstpassword --dstdatabasename=dbyy --ignoretables=TableToIgnore --cleardstdatabase

As you can tell, the arguments prefixed 'src' concern the source database and the arguments prefixed 'dst' concern the destination database. If there's no credentials in use, when you're using Windows Authentication, just omit the 'username' and 'password' arguments. You can leave off the 'ignoretables' argumen if you want every table in the source database to be copied to the destination database. The 'cleardstdatabase' argument isn't necessary for now.

It should take under a minute to transfer your inital Orchard data in your local database to your remote AppHarbor hosted database.

10. Change the connection string in /App_data/Sites/Default/Settings.txt to your AppHarbor database.

We're almost done now. All we have to do is push the data to BitBucket and your site will be up and running on AppHarbor. But before you do, you'll need to change the connection string in your Orchard application to point to your remote database otherwise your Orchard website hosted on AppHarbor will try to connect to your local database which would probably fail.

Oddly enough, the Orchard team decided not to place the connection string in the web.config file like most applications but instead place it in a plain-text settings file. Why? I haven't read up on too much of the rationale to explain it properly so I won't try. Until I figure out a better and more secure way to do this without messing with the source code of Orchard, it looks like we'll have to place our connection string of our remote AppHarbor database right there.

You can find the settings file at '/App_data/Sites/Default/Settings.txt'. Here's a glimpse of what you'll find:

Name: Default
DataProvider: SqlServer
DataConnectionString: Data Source=.\DEV;Initial Catalog=EPC_DB;Integrated Security=True
DataPrefix: EPC
RequestUrlHost: null
RequestUrlPrefix: null
State: Running
EncryptionAlgorithm: AES
EncryptionKey: {some long encryption key}
HashAlgorithm: HMACSHA256
HashKey: {a long hash key}
See the third line named DataConnectionString? That's where you'll need to paste in your remote AppHarbor database connection string.

11. Commit to your local repository then push to your BitBucket repository

All that's left to do is to make a commit to your local repository and push your repository to BitBucket.

After pushing your application to BitBucket, AppHarbor will get word that your repository has a new commit, pull in the changes and 'build' and deploy your application. I placed the word build in quotes in the previous sentence because AppHarbor isn't really going to build anything. There's no solution file in our repository which AppHarbor needs to build code. However, AppHarbor will happily deploy and run DLLs you push to it. So it looks like you don't have to release the source code of your next killer app to the folks at AppHarbor. What up Heroku!

If all goes well, your Orchard website should be up-and-running on AppHarbor. You can get the URL for your app under the left-hand side menu over at AppHarbor. It ought to be "" unless someone else happened to have picked the same app name, in which case you'll have some number appeneded to your application name.

Congratulatinos! Your website is now up and running on AppHarbor.

Here's one more step you'll have to take when working on your website after initial deployment.

12. Change your connection string back to your local database

Creating new pages and or posting blog entries can be done online via the dashboard. This is because those kind of tasks make no changes to your deployed code and persist information to the database.

However, if you want to add a new theme or module or maybe hack away in some other part of the codebase, you'll need to do so locally and then push the changes to AppHarbor via BitBucket. It'll be pretty slow if you have to develop your website against the remote database so change the connection string in your setting file back to the local database. Do remember, when you do commit your changes, don't commit the local connection string to your repository. I don't know if you should be expecting any other changes to your settings file so I'd advise you to review what's changed in your settings file via git/hg before each commit to make sure the only change is the connection string. If the connection string is the only change then you don't need to commit the file.


This post turned out far longer than I thought it would be. If you feel like I could improve some parts of it, let me know. I don't blog or do much writing so if you enjoyed this post and are interested in hearing more about Orchard, ASP.NET MVC or C# from me, let me know in the comments and hopefully that'll encourage me to write more stuff.

Comments require approval before they show up.


Add a Comment