Recently I decided to explore developing web applications with Haskell. I did some searching and it appeared to me that Yesod is one of the most full-featured Haskell web frameworks available. I decided to give it a hello world try and I must say I did struggled a bit before I finally managed to get it to load successfully on Heroku. Therefore I decided to write this post to share what I did to get it to work.
This blog post’s purpose is just to demonstrate the deployment of a Yesod app onto Heroku. In this version of the Yesod, there is no database support. It will just be a simple site. There will be little info about Yesod and Haskell itself. I also assume you have some experience with Git and Heroku.
1 Getting Started
To begin, you’ll first need the Haskell Platform. After you installed it, fire up your terminal and you should have the
cabal commands. See the following for the versions I was using:
1 2 3 4 5 6
Next, you’ll need to install Yesod. But before that, I’d suggest you update your
cabal. To do that, run:
When that’s done, you can install Yesod by running:
After you are done, you should have the
yesod command in your terminal.
You’ll then need to install the Heroku Toolbelt.
2 Scaffold A Yesod Site
You might have heard of the ability to quickly generate a skeleton-like, minimal and working site on Ruby on Rails. Yesod allows you to do that too, and we’ll be using a scaffolded site to deploy onto Heroku. To do that, run:
The tool helps you scaffold a site by asking you a few questions. Here’s how it was when I ran it (Note that I gave my project the name yesod-simple):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
In this example, I chose simple. Then the magic will happen and you will see more text output in your terminal. Just take note of the last line, it should look something like:
Simple, it navigates into the yesod-simple directory, runs a
cabal install command and finally a
yesod devel command. What
cabal install does is that it will look at the generated yesod-simple.cabal file and installs all the required stuff the project needs. For this example, you shouldn’t need to modify this generated .cabal file. (For those who have heard of sandboxing, you can look up the command
cabal sandbox init. It actually is the recommended way). Finally the
yesod devel command will start a local instance of the server on your machine. It will perform some compilation, and when it is done, you can preview the site at:
If you see “Welcome to Yesod!”, then you are doing good. You should now initialize a git repository using the following commands:
1 2 3
3 Create A Heroku App
You are now ready to set up your Heroku site using this Yesod app you just generated. You will be using the Haskell Buildpack in the process. First create your Heroku app by running the following command. Notice that the build pack has been specified as a command parameter.
After you ran that command, you should get a response from Heroku saying your app has been created and it has been given a fancy name like snow-storm-871. Rename it like this:
4 Configure & Build Your Yesod App
From the previous step, you should have the name of your Heroku app already. For my case, it is yesod-simple. What’s going to happen now is that you are going to configure your Yesod app, and then build it using the command
yesod keter. Now, I want you to open the file
config/keter.yml using your favourite text editor. If you read the file, you should see that the instructions given in the commented lines are actually quite straightforward.
- First thing you want to do is remove the line that says user-edited: false (or if you prefer, like me, set it to
- Then you update the hosts. If you follow my example so far, it should say www.yesod-simple.com. Change it to yesod-simple.herokuapp.com.
- In fact, since your Heroku site will be yesod-simple.herokuapp.com, you should update all the lines that has www.yesod-simple.com or yesod-simple.com. (You can refer to my
config/keter.ymlin my github repo)
- Save the file. You are now ready to build your Yesod app.
Build your Yesod app by running the command
yesod keter. In the process you should numerous Loading package… lines and Compiling… lines. But at the end of it, you should have something like:
This is the binary that is built from the command that you just executed. Take note of this path, you will be using it shortly. Make a
git commit here.
5 Create A Procfile For Heroku
In order for Heroku to start and run your app, you need to tell it to run it. You do that by specifying your instructions in a Procfile. Create a file named Procfile and in this file specify the following:
This simply tells Heroku, “Hey Heroku, my app is a webapp. Please start and run it using that command I just gave you.”.
git commit your changes so far.
6 Build Your Heroku App Using An Anvil Server
If you tried Heroku before, when you do a
git push heroku master, it uploads your changes onto Heroku and it triggers a build of your app. If that takes more than 15 mins, Heroku will terminate it. Your Yesod app will certainly take more than 15 mins. That’s why you need to build it using an Anvil server. To do that, you need to install a plugin to your Heroku app:
Now you can get Anvil to build your Heroku app for you. But before that, you would want to move your dist folder out of your project folder first. After that, you can trigger the build process like this:
This command will take a while, so go ahead and grab a cup of tea. What happens when you run the command is:
- Tell Heroku to download and install all the stuff specified in the buildpack. This is the part that takes quite a lot of time
- Build, and then cache the build on an Anvil server. The cache should be saved at https://api.anvilworks.org/cache/CACHE_ID.tgz
- Keep track of this CACHE_ID in your
Next you need to tell your Heroku app where to get this cached build. To do that:
So when you
git push heroku master, your Heroku app will retrieve that cache.
git add all the modified files so far and then
git push heroku master. In the process, you should see that your files are being uploaded, Heroku is picking up that it is a Haskell app, it retrieves your cached build etc. If everything goes well, you see that your app was launched on Heroku.
You can then visit your Yesod site at http://yesod-simple.herokuapp.com.
Welcome to Yesod!
I hope the above instructions worked for you. If you like, you can find my copy of the above at my GitHub repo yesod-simple.