From 4023e7f4e429179fd9c2cce4487c33646c6bd327 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Thu, 14 Jan 2016 13:35:25 +0100
Subject: Convert the documentation to Asciidoc

A few small revisions were made, and Erlang.mk has been updated.
---
 doc/src/guide/getting_started.asciidoc | 136 +++++++++++++++++++++++++++++++++
 1 file changed, 136 insertions(+)
 create mode 100644 doc/src/guide/getting_started.asciidoc

(limited to 'doc/src/guide/getting_started.asciidoc')

diff --git a/doc/src/guide/getting_started.asciidoc b/doc/src/guide/getting_started.asciidoc
new file mode 100644
index 0000000..5d72f0a
--- /dev/null
+++ b/doc/src/guide/getting_started.asciidoc
@@ -0,0 +1,136 @@
+[[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 https://github.com/ninenines/erlang.mk[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.
+
+[source,bash]
+$ mkdir hello_erlang
+$ cd hello_erlang
+
+Then we need to download Erlang.mk. Either use the following
+command or download it manually.
+
+[source,bash]
+$ 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.
+
+[source,bash]
+$ 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.
+
+[source,bash]
+----
+$ 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 one line
+to our Makefile to make it look like this:
+
+[source,make]
+PROJECT = hello_erlang
+DEPS = cowboy
+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:
+
+[source,erlang]
+----
+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
+xref:routing[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.
+
+[source,bash]
+$ 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.
+
+[source,erlang]
+----
+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!
-- 
cgit v1.2.3