Getting Started with Nitrogen

• Is there a Nitrogen Tutorial?
• 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?

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

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:

git clone https://github.com/nitrogen/nitrogen

Then 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 with Mochiweb, Yaws, Cowboy, or Webmachine. Run one of the following make commands:

make rel_mochiweb
make rel_yaws
make rel_cowboy
make rel_webmachine

Note: There are special instructions for Windows users who wish to compile on Windows. Read about Compiling Nitrogen on Windows

To start Nitrogen in the console

bin/nitrogen console

To start Nitrogen, type

bin/nitrogen start

To attach to a detached Nitrogen console

bin/nitrogen attach

To stop Nitrogen

bin/nitrogen stop

Read all about the configuration options.

Your entire site's code can be found in site/.

Within there, you'll find:

site/src

Your erlang code

site/static

Where static resources like CSS, Javascript, and Images Go

site/templates

Where your site's HTML templates go

site/ebin

Where the compiled BEAM files go.

It is currently recommended to play the site/ directory under source control.

There are three different ways to compile code in Nitrogen:

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

  This will start the sync process, which scans the filesystem for changes and automatically recompiles modules as they are changed.

  Note: sync will only recompile files that are changed after sync was started. That means that if sync is not currently running, and you change a file, it will not detect that change.

• 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.

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.

If you're running a a version of Nitrogen 2.1.0 and above:

• Run

  make upgrade
  

  This will upgrade to the latest version of Nitrogen and it's dependencies. It will not upgrade to the latest Erlang Runtime System. If you wish to upgrade your version of ERTS, You'll want to follow the directions below for upgrading from pre-2.1 to 2.1+.

If you're running a version of Nitrogen pre 2.1 and want to upgrade to 2.1.0 and above:

• 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.