# vim: ts=2 sw=2 et ft=org
#+STYLE: <LINK href="stylesheet.css" rel="stylesheet" type="text/css">
#+TITLE: Getting Started with Nitrogen
#+AUTHOR: Rusty Klophaus (@rustyio)
#+EMAIL: 

#+TEXT: *Getting Started* | [[file:./api.org][API]] | [[file:./elements.org][Elements]] | [[file:./actions.org][Actions]] | [[file:./validators.org][Validators]] | [[file:./handlers.org][Handlers]] | [[file:./config.org][Configuration Options]] | [[file:./about.org][About]]
#+HTML: <div class=headline>Getting Started</div>

* Common Questions

  + [[0][Is there a Nitrogen Tutorial?]]
  + [[1][How do I create a new Nitrogen application?]]
  + [[2][How do I start and stop my application?]]
  + [[3][How do I change configuration settings?]]
  + [[4][Where is the code for my website?]]
  + [[5][How do I compile my code?]]
  + [[6][How do I create new pages, custom elements, or custom actions?]]
  + [[7][How do I upgrade to a new version of Nitrogen?]]

* Is there a Nitrogen Tutorial?
# <<0>>

  Yes! You can [[file:./tutorial.org][view the updated slides]] from Rusty's Nitrogen Tutorial at the
  Erlang User Conference 2010 here.
  
* How do I create a new Nitrogen application?
# <<1>>

  First, check the [[http://nitrogenproject.com/downloads][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 [[http://nitrogenproject.com/downloads][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 
  [[https://github.com/nitrogen/nitrogen/blob/master/rel/overlay/win/README.md][Compiling Nitrogen on Windows]]

* How do I start/stop/manage Nitrogen?
# <<2>>

  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

* How do I change configuration settings?
# <<3>>

  Read all about the [[file./config.org][configuration options]].

* Where is the code for my website?
# <<4>>

  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.

* How do I compile my code?
# <<5>>

  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.

* How do I create new pages, custom elements, or custom actions?
# <<6>>

  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. 

* How do I upgrade to a new version of Nitrogen?
# <<7>>

  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.

