Author: Rusty Klophaus (@rklophaus)

# Getting Started with Nitrogen

Getting Started | API | Elements | Actions | Validators | Handlers | About

Getting Started

## Table of Contents

- 1 Common Questions
- 2 Is there a Nitrogen Tutorial?
- 3 How do I create a new Nitrogen application?
- 4 How do I start/stop/manage Nitrogen?
- 5 How do I change configuration settings?
  - 5.1 Inets Configuration
  - 5.2 Mochiweb Configuration
  - 5.3 Yaws Configuration
- 6 Where is the code for my website?
- 7 How do I compile my code?
- 8 How do I create new pages, custom elements, or custom actions?
- 9 How do I upgrade to a new version of Nitrogen?

## 1 Common Questions

- How do I create a new Nitrogen application?
- How do I start and stop my application?
- How do I change configuration settings?
- Where is the code for my website?
- How do I compile my code?
- How do I create new pages, custom elements, or custom actions?
- How do I upgrade to a new version of Nitrogen?

## 2 Is there a Nitrogen Tutorial?

Yes! You can view the slides from Rusty's Nitrogen Tutorial at the Erlang User Conference 2010 here.

## 3 How do I create a new Nitrogen application?

First, check the Downloads page to see if a pre-built package exists for your OS/architecture. If it does, then just download the package, unzip, and you are ready to start coding. (You don't even need to have Erlang installed, the Nitrogen binaries come with it pre-packaged.)

If you don't see a package that will run on your computer, or you want to try running from the latest code in source control, then follow the steps below:

Pull the latest source code from GitHub and run:

    make rel_inets

This creates a completely self-contained starter application under `./rel/nitrogen` that runs on Inets, Erlang's built in HTTP server. "Self-contained" here means that the `./rel/nitrogen` directory contains everything you need to develop and run nitrogen, including the Erlang VM. To create a `.tar.gz` version of this code, exactly like you would find on the Downloads page, run:

    make package_inets

You can also run Nitrogen on Mochiweb or Yaws. Run one of the scripts provided in the `./deps/` directory to download the Mochiweb or Yaws code.

    # For Mochiweb...
    ./deps/get_mochiweb.sh

    # For Yaws...
    ./deps/get_yaws.sh

Then, create the release or the binary package (example below is for Mochiweb):

    # Build a release in ./rel/nitrogen
    make rel_mochiweb

    # Build a binary package in ./builds
    make package_mochiweb

Nitrogen 2.0 uses Dave "Dizzy" Smith's Rebar (source code) to build OTP-compliant releases and packages. Check it out, it is awesome.

## 4 How do I start/stop/manage Nitrogen?

Once you have a build of Nitrogen that will run on your application, the next step is to start the application. Nitrogen includes a handy script inside your release, under `./bin/nitrogen`, that will let you bring your Nitrogen application up or down:

    # Start the app in the background...
    ./bin/nitrogen start

    # Connect to the app in the background. Control-D to disconnect.
    ./bin/nitrogen attach

    # Stop the app...
    ./bin/nitrogen stop

    # Start the app in "console" mode...
    ./bin/nitrogen console

    # Ping the app to see if it is running...
    ./bin/nitrogen ping

Once you have started your application, open http://localhost:8000. You should see a basic welcome page.x

## 5 How do I change configuration settings?

All configuration files for your application can be found under the `./etc` directory.

Here, you will see:

- vm.args - This controls the arguments passed in to the VM. Here, you can set the node name, cookie, memory flags, etc.
- app.config - This contains application settings for Nitrogen and sasl (error logging).

Important: Before deploying your app to production, you should change the Erlang cookie (found in `./etc/vm.args`) and define a Nitrogen signkey (found in `./etc/app.config`).

### 5.1 Inets Configuration

Nitrogen applications running on Inets will also contain:

- inets.config - You should not need to touch this file.
- inets_httpd.erlenv - Configure ip/port of your application, and other Inets-specific information.

### 5.2 Mochiweb Configuration

Nitrogen applications running on Mochiweb will also contain:

- mochiweb.config - Configure ip/port of your application, and other Mochiweb-specific information.

### 5.3 Yaws Configuration

Nitrogen applications running on Yaws will also contain:

- yaws.config - You should not need to touch this file.
- yaws.conf - Configure ip/port of your application, and other Yaws-specific information.

## 6 Where is the code for my website?

The Nitrogen project is structured so that all site specific code is contained inside the `site` directory. It is recommended that you place your entire `site` directory under source control. This will allow you to move your application to other architectures and configurations easily.

The `site` directory contains the following sub-directories:

`./site/src`
  Page modules, custom elements, and custom actions for your site.
`./site/static`
  Static files, including Javascript and CSS. These will be served through the web. Place any files you like here, but try not to touch the `nitrogen` directory, as you will need to overwrite this when you upgrade to a new version of Nitrogen.
`./site/templates`
  Html files used by the `#template{}` action.
`./site/.prototypes`
  Code used by `./bin/dev` to generate a page, element, or action. Feel free to edit these to something more to your liking.
`./site/ebin`
  Compiled `.beam` files.

## 7 How do I compile my code?

There are three different ways to compile code in Nitrogen:

- If you are in the Erlang console then run `sync:go().`

  This will look at all loaded modules, find their associated Emakefiles, and run `make:all([load]).` to recompile.

- If Nitrogen is running in the background then run `./bin/dev compile`

  This connects to the running Nitrogen application and issues a `sync:go().` command.

- If Nitrogen is stopped then run `make compile`

  This calls `erl -make`, causing your application to be compiled based on the provided Emakefile.

## 8 How do I create new pages, custom elements, or custom actions?

Nitrogen 2.0 includes a developer tool to help you get started with a bare-bones page, element, or action. This tool uses the files found in `./site/.prototypes` as templates. If you wish, you can edit files in this directory to make them more suitable for your application.

- To create a new page at http://localhost/user/login, run:

      ./bin/dev page user_login

- To create a new element called `#custom_element{}`, run:

      ./bin/dev element custom_element

- To create a new action called `#custom_action{}`, run:

      ./bin/dev action custom_action

The code is placed under `./site/src`, `./site/src/elements`, or `./site/src/actions` for pages, elements, and actions, respectively.

## 9 How do I upgrade to a new version of Nitrogen?

To upgrade to new versions of Nitrogen 2.0:

- Build or download the new Nitrogen environment for your architecture and preferred web server. Unzip to a new directory.
- Copy your existing `./etc` directory to the new build. This retains your configuration settings.
- Copy your existing `./site` directory to the new build, except for the files in `./site/static/nitrogen`. You will want to use the new version of any files in `./site/static/nitrogen`.

This will update the Erlang version, the dependencies files, and all of the Javascript used by Nitrogen.

You will also need to update your code if there are any API level changes.

Author: Rusty Klophaus (@rklophaus)

Date: 2010-11-22 11:07:12 EST

HTML generated by org-mode 7.01h in emacs 24