This tutorial will walk you through creating a working Hunchentoot project, including how to test it locally and deploy it to Heroku. I believe that, if your goal is to learn Hunchentoot, you should not get hung up on the setup. Thus, this tutorial is meant to be quick and easy, with the goal of getting Hunchentoot set up as quickly and easily as possible.
This was tested on Windows 8 so far – it may be edited to include instructions for other operating systems in the near future.
Prerequisites:
- A Heroku account with the heroku toolbelt installed
- Git and git bash
- curl
- sbcl with quicklisp
Create your Hunchentoot project
First, we’ll be using this git repository to create our first Hunchentoot project. This is a really nice repo hosted by bhyde@github that will set up your project, deploy it to Heroku, and open it in your default web browser with a single command.
First, open up git bash. Right-click on your desktop or in a folder and you might see an option to “Open git bash here”. If not, you can open up the “search” function on your computer and type “git bash” to find it. Make sure you’re logged into heroku as well with this command (it will prompt you for a username and password):
heroku login
Next, navigate to a folder that you want to create your project in.
cd ~/documents
Create a directory to house your project, and then navigate inside that directory using cd:
mkdir hunchentoot cd hunchentoot
Now, run the following command and wait for it to finish. It will create a new Hunchentoot project for you, deploy it to heroku, and then open it in your web browser.
curl https://gist.github.com/bhyde/5383182/raw/gistfile1.txt | bash
Voila! You should now see a webpage with an image saying “Built with Lisp”.
As you may have noticed, this heroku app was created with a default heroku name. To change this, go to your heroku dashboard and click the “settings” icon next to the app name (it looks like a pair of gears). This will take you to a page where you can change your app’s name to anything you like. Then, go back into your hunchentoot folder. You’ll notice a folder with the name of your app – change it to the new name, whatever you picked. There is one last place where you need to make a change: in a file called “config”, in a folder called git. Near the end of the file, you will see your old app name. Change it to your new, and everything should be fine.
How did this work?
Here’s a quick and basic explanation for those curious about how bhyde’s git repo works. Heroku does not have official support for Lisp/Hunchentoot, so how did all of this work? It turns out that the repository creates a “buildpack” for Heroku, which uses CCL’s “save-application” feature to dump an image of your app into an executable file named “lispapp”. The Procfile (which Heroku uses to determine what to run) instructs Heroku to run this executable.
Testing/Running the Server Locally
Hunchentoot requires OpenSSL, which you can download and install from here. (Scroll down to “Win32 OpenSSL v1.0.1f” and run the executable.) Now, once again open git bash and navigate to your project directory (the folder with the same name as your app, not the one containing this folder). You want to be in the same directory as the file “main.lisp”.
Now, open up your repl:
sbcl
In the repl, we will be typing three commands: One to load hunchentoot, one to load main.lisp, and one to start the server.
We will use quicklisp to load hunchentoot:
(ql:quickload :hunchentoot)
Now, we load our main.lisp, as this is the file containing instructions about creating and rendering our webpage:
(load "main.lisp")
Finally, start the server using this line. You can replace “8000” below with any port number you’d like, and it will attempt to run the server on that port. The initialize-application function, by the way, is defined towards the bottom of “main.lisp”.
(initialize-application :port 8000)
You can now see the server running by going to this address in your browser:
http://127.0.0.1:8000
where you can replace “8000” with the port you chose to run the server on.
Now, this is all a lot to type when you want to run the server, so let’s put all of this in a single file. A reasonable name for this file would be runserver.lisp. We simply put the commands inside of this file like so:
(ql:quickload :hunchentoot) (load "main.lisp") (initialize-application :port 8000)
Now, you can run the server by simply loading “runserver.lisp” from the repl. You can quit the server with Ctrl+C.
Making Static Files Show Up Locally
You may notice a folder named “static” in your app. This is where all of your static files reside, for example, images. In order for these to show up, you need to modify the static path in main.lisp.
Luckily, this is not so hard. Open up main.lisp in your favorite editor. Now, look for a call to hunchentoot:create-folder-dispatcher-and-handler.
Change the second argument to the location of your static files, which for this project is the folder “static/”. Thus, in the end, this is what you should have:
;; Set the dispatch table so easy-handler pages are served, ;; and the files in <root>/static. (setf hunchentoot:*dispatch-table* `(hunchentoot:dispatch-easy-handlers ,(hunchentoot:create-folder-dispatcher-and-handler "/" "static/")))
Deploying Changes to Heroku
Made some changes to your website? Ready for production? You can deploy your new and improved app to Heroku with two simple commands:
git commit -m "type a message about your changes here" . git push heroku master
Now, your changes should be visible online. You can view them by going to your app manually, or by using the command:
heroku open
which will open your app up in your default web browser.
cheryllium 