Nine Nines: Getting started

Getting started

Erlang is more than a language, it is also an operating system +for your applications. Erlang developers rarely write standalone +modules, they write libraries or applications, and then bundle +those into what is called a release. A release contains the +Erlang VM plus all applications required to run the node, so +it can be pushed to production directly.

This chapter walks you through all the steps of setting up +Cowboy, writing your first application and generating your first +release. At the end of this chapter you should know everything +you need to push your first Cowboy application to production.

Bootstrap

We are going to use the Erlang.mk +build system. It also offers bootstrap features allowing us to +quickly get started without having to deal with minute details.

First, let’s create the directory for our application.

$ mkdir hello_erlang
+$ cd hello_erlang

Then we need to download Erlang.mk. Either use the following +command or download it manually.

$ wget https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk

We can now bootstrap our application. Since we are going to generate +a release, we will also bootstrap it at the same time.

$ make -f erlang.mk bootstrap bootstrap-rel

This creates a Makefile, a base application, and the release files +necessary for creating the release. We can already build and start +this release.

$ make run
+...
+(hello_erlang@127.0.0.1)1>

Entering the command i(). will show the running processes, including +one called hello_erlang_sup. This is the supervisor for our +application.

The release currently does nothing. In the rest of this chapter we +will add Cowboy as a dependency and write a simple "Hello world!" +handler.

Cowboy setup

Modifying the Makefile allows the build system to know it needs to +fetch and compile Cowboy. To do that we simply need to add two lines +to our Makefile to make it look like this:

PROJECT = hello_erlang
+
+DEPS = cowboy
+dep_cowboy_commit = master
+
+include erlang.mk

If you run make run now, Cowboy will be included in the release +and started automatically. This is not enough however, as Cowboy +doesn’t do anything by default. We still need to tell Cowboy to +listen for connections.

Listening for connections

We will do this when our application starts. It’s a two step process. +First we need to define and compile the dispatch list, a list of +routes that Cowboy will use to map requests to handler modules. +Then we tell Cowboy to listen for connections.

Open the src/hello_erlang_app.erl file and add the necessary +code to the start/2 function to make it look like this:

start(_Type, _Args) ->
+        Dispatch = cowboy_router:compile([
+                {'_', [{"/", hello_handler, []}]}
+        ]),
+        {ok, _} = cowboy:start_http(my_http_listener, 100, [{port, 8080}],
+                [{env, [{dispatch, Dispatch}]}]
+        ),
+        hello_erlang_sup:start_link().

The dispatch list is explained in great details in the +Routing chapter. For this tutorial we map the +path / to the handler module hello_handler. This module +doesn’t exist yet, we still have to write it.

If you build and start the release, then open http://localhost:8080 +in your browser, you will get an error because the module is missing. +Any other URL, like http://localhost:8080/test, will result in a +404 error.

Handling requests

Cowboy features different kinds of handlers, including REST +and Websocket handlers. For this tutorial we will use a plain +HTTP handler.

First, let’s generate a handler from a template.

$ make new t=cowboy_http n=hello_handler

You can then open the src/hello_handler.erl file and modify +the init/2 function like this to send a reply.

init(Req, Opts) ->
+        Req2 = cowboy_req:reply(200,
+                [{<<"content-type">>, <<"text/plain">>}],
+                <<"Hello Erlang!">>,
+                Req),
+        {ok, Req2, Opts}.

What the above code does is send a 200 OK reply, with the +content-type header set to text/plain and the response +body set to Hello Erlang!.

If you run the release and open http://localhost:8080 +in your browser, you should get a nice Hello Erlang! displayed!

99s

Getting started

Bootstrap

Cowboy setup

Listening for connections

Handling requests

+ Cowboy + 2.0 + + User Guide +

Navigation

Version select