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.