PieCrust on Heroku

When I first decided to work on PieCrust, I settled with PHP as the language – even though it mostly sucks – in an attempt to make it broadly available. Anybody who runs a blog on WordPress should be able to switch and enjoy the perks of plain text data without needing to install and learn a whole new environment.

That doesn’t mean PieCrust can’t also be used in the nerdiest ways possible. A while ago we looked at how cool it is to update your website with Git or Mercurial, and today we’ll look at how you can host it on Heroku, which incidentally also supports Git-based deployment.

If you already know how Heroku works, then the only thing you need is to make your app use the custom PieCrust buildpack. Skip to the end for a few details about it.

For the rest, here’s a detailed guide for setting up your PieCrust blog on Heroku, after the break.

1. Sign up and setup

This is pretty obvious but it’s still a step you’ll have to go through: sign up for a Heroku account and install their tools. Follow the first step to login via the command line, but don’t create any app just now.

2. Create your PieCrust website

For the sake of this tutorial, let’s start with a fresh new site. You will of course be able to use an existing one, the steps would be very similar.

Let’s create one called mypiecrustblog:

> chef init mypiecrustblog
PieCrust website created in: mypiecrustblog/

Run 'chef serve' on this directory to preview it.
Run 'chef bake' on this directory to generate the static files.

Let’s also add a post, just to be fancy:

> chef prepare post hello-heroku
Creating new post: _content/posts/2012-12-03_hello-heroku.html

Last, turn the site into a Git repository, make Git ignore the _cache directory, and commit all your files:

> git init .
Initialized empty Git repository in /your/path/to/mypiecrustblog/.git/
> echo _cache > .gitignore
> git add .
> git commit -a -m "Initial commit."

By the way, you can quickly check what the site looks like locally with chef serve. We should be able to see the exact same thing online in a few minutes when it’s running on Heroku.

3. Create your Heroku app

Now we’ll turn our site into a Heroku app. The only difference with the documentation on the Heroku website for this is that we’ll add an extra command line parameter to tell it that it’s a PieCrust application:

> heroku create mypiecrustblog --buildpack https://github.com/ludovicchabant/heroku-buildpack-piecrust.git
Creating mypiecrustblog... done, stack is cedar
BUILDPACK_URL=https://github.com/ludovicchabant/heroku-buildpack-piecrust.git
http://mypiecrustblog.herokuapp.com/ | git@heroku.com:mypiecrustblog.git
Git remote heroku added

What’s happening here is that, in theory, Heroku doesn’t know about any programming language or development environment – instead, it relies on “buildpacks” to tell it what to do to set up and run each application. It has a bunch of default buildpacks for the most common technologies, but it wouldn’t know what to do with a PieCrust website so we need to provide our own buildpack, with that --buildpack parameter.

If you already created you app previously, you can also make it a PieCrust application by editing your app’s configuration like this:

heroku config:add BUILDPACK_URL=https://github.com/ludovicchabant/heroku-buildpack-piecrust

We can now push our website’s contents to Heroku:

> git push heroku master
Counting objects: 3, done.
Writing objects: 100% (1/1), 185 bytes, done.
Total 1 (delta 0), reused 0 (delta 0)

-----> Heroku receiving push
-----> Fetching custom git buildpack... done
-----> PieCrust app detected
-----> Bundling Apache version 2.2.22
-----> Bundling PHP version 5.3.10
-----> Bundling PieCrust version default
-----> Reading PieCrust Heroku settings
-----> Baking the site
[   171.7 ms] cleaned cache (reason: not valid anymore)
[    46.4 ms] 2012/12/03/hello-heroku
[    21.3 ms] [main page]
[     2.2 ms] css/simple.css
-------------------------
[   247.3 ms] done baking
-----> Discovering process types
       Procfile declares types    -> (none)
       Default types for PieCrust -> web
-----> Compiled slug size: 9.5MB
-----> Launching... done, v7
       http://mypiecrustblog.herokuapp.com deployed to Heroku

To git@heroku.com:mypiecrustblog.git
   1180f39..e70c271  master -> master

At this point, you should be able to browse your website on Heroku (http://mypiecrustblog.herokuapp.com in our case here).

You now just need to keep adding content, and git push to make it available online.

Appendix: The PieCrust buildpack

The PieCrust buildpack we’re using in this tutorial will, by default, bake your website and put all the generated static files in the www folder for the world to enjoy.

If, however, you set the heroku/build_type site configuration setting to dynamic, it will copy the PieCrust binary (a .phar archive) to your app’s folder and create a small bootstrap PHP script that will run PieCrust on each request. This would make deployments very fast, as you won’t have to wait for the website to re-bake, but it’s highly recommended that you use a good cache or reverse proxy for anything else than test websites.

Note that the version of PieCrust that’s used by the buildpack is, by default, the latest one from the development branch (default in Mercurial, master in Git). You can change that with the PIECRUST_VERSION environment variable. For example, to use the stable branch instead, you can do:

> heroku config:add PIECRUST_VERSION=stable

For more information about the buildpack, you can simply go check the source code over on Github.