Go to page content

Just enough Webmachine

Getting a solid foundation for your Zotonic skillset.


Zotonic talks to the web through a wonderful Erlang-based http REST toolkit called Webmachine. Webmachine was generously contibuted to the open-source world by Basho of Cambridge, MA.

A basic understanding of Webmachine will provide a solid foundation for your Zotonic skillset.

This Cookbook recipe will give you hands-on experience with Webmachine, Webmachine resources, and how to modifify a Webmachine resource.


You have git, a recent version of Erlang, and Zotonic installed on your system.

You have basic Linux shell and program editing competencies.

You have basic sequential Erlang skills and understand the structure of Erlang modules.


We'll install and compile Webmachine, create a simple demo application, and modify and execute a Webmachine resource. Finally, we'll take a brief look at how Zotonic integrates Webmachine.

NOTE: Your Zotonic install already includes a webmachine instance. But we'll install another instance so you can play.

What is Webmachine?

Webmachine handles well-formed http REST requests, gracefully handles all errors, and provides powerful debugging tools.

A Webmachine application is a set of resources written in Erlang, each of which is a set of functions over the state of the resource

These functions give you a place to define the representations and other Web-relevant properties of your application's resources

How can I explore Webmachine?

Make sure that you have a working Erlang/OTP release, R12B5 or later.

Get the webmachine code:

git clone git://github.com/basho/webmachine

Build webmachine:

cd webmachine

Create, build, and start the skeleton resource:

NOTE: An error in the Webmachine quickstart instructions reads:

./scripts/new_webmachine.erl mywebdemo /tmp

It should be:

./scripts/new_webmachine.sh mywebdemo /tmp
cd /tmp/mywebdemo

You should see a series of progress reports

Point a web browser at http://localhost:8000/

You should now see Hello, new world

How can I stop the demo?

Press ctl C, then press a

How can I examine the resource that produced the hello-world message?

$ cd /tmp/mywebdemo/src

Open mywebdemo_resource.erl in your favorite code editor.

How can I modify the resource to execute and display my own Erlang function?

Make the following changes mywebdemo_resource.erl just under the init/1 function:

earthman() ->
        "Earth man!".

to_html(ReqData, State) ->
    {"<html><body>Hello, " ++ earthman() ++ "<body></html>", ReqData, State}.


cd ..

mywebdemo$ make

Now, from your web browser, refresh http://localhost:8000.

You should see your change.

You'll find more Webmachine documentation at: http://webmachine.basho.com/docs.html. It'll take you pretty much wherever you want to go.

You now know enough about Webmachine to understand how Zotonic communicates through the web.

So how does Zotonic integrate Webmachine?

Peek into the following directory:

NOTE: path may differ slightly on your system.

$ cd /home/zotonic/zotonic/deps

You'll see the webmachine directory. It's contents will be familiar from your explorations above.

(NOTE: At this point I'm lost. Need a Zotonic wizard to fill in from here. Marc or Arjan, please edit and expand to provide authoritative overview.)


$ cd ../src

With your favorite code editor, open up zotonic_sup.erl and search for "webmachine."

(Marc: Please expand, if you think useful)


$ cd ../priv/sites/blog/resources

Open resource_default_contact.erl.



There are no troubleshooting steps available for this item. If you find a problem or workaround, please mention it in the comments below or on Zotonic Users.



This page is part of the Zotonic documentation, which is licensed under the Apache License 2.0.