Documentation

Configuration Options

Configuration Overview

Nitrogen configuration is done in a handful of different configuration files, and also varies slightly between backend servers. All of these files are found in the etc/ directory of your Nitrogen installation. Below we will go though the configuration options provided within each.

It's worth noting that Nitrogen has a small modification to the standard rebar start script allow you to break configuration files up into multiple files. Otherwise, you'd have to mash all these files into a single configuration file. A minor convenience, but the Erlang veterans might wonder why this even works.

Univeral Configuration Files (configs available in all Nitrogen intallations)

`etc/vm.args`

This is the file that sends sends options to the Erlang Virtual Machine. Basically, any of the usual erl startup parameters will work here. You'll define some standard options here, such as the node name, (-name), erlang cookie (-cookie), some miscellaneous environment options, and of course, to tell the system to launch the Nitrogen application upon startup.

Here is the complete text of the default vm.args:

  ## Name of the Nitrogen node
  -name nitrogen@127.0.0.1

  ## Cookie for distributed erlang
  -setcookie nitrogen

  ## Heartbeat management; auto-restarts VM if it dies or becomes unresponsive
  ## (Disabled by default..use with caution!)
  ##-heart

  ## Enable kernel poll and a few async threads
  +K true
  +A 5

  ## Increase number of concurrent ports/sockets
  -env ERL_MAX_PORTS 4096

  ## Tweak GC to run more often
  -env ERL_FULLSWEEP_AFTER 10

  ## Include .beam files for site.
  -pa ./site/ebin

  ## Include libraries and rebar dependency paths
  -env ERL_LIBS ./lib

  ## Run code at startup.
  -eval "application:start(nitrogen)"

`etc/app.config`

This file contains the configuration options for the Nitrogen application itself. It uses the standard Erlang config syntax: (a proplist of {applicationName, AppOptions}).

For the nitrogen application, the following AppOptions are recognized:

signkey (String) - signkey is the term that Nitrogen usees to "sign" the state information that's sent to the client, and then resent back to the server with requests. While Nitrogen's state info is not encrypted, this is used to help verify that the term generated is actually generated by Nitrogen, to prevent client-side tampering with the state.
session_timeout (integer) - session_timeout is the number of minutes a session can be idle before Nitrogen expunges it from memory
cookie_name (string) - cookie_name is the name of the HTTP Cookie to be used as the sesson tracking cookie. This is not to be confused with the Erlang Cookie, which is defined in the vm.args file above.

Also typically defined in the app.config file here is the SASL Configuration, the default of which for Nitrogen can be seen here:
module_prefix (string) - This provides the user with the ability to route all Nitrogen web requests to modules that all share the same prefix. For example, if module_prefix was set to "abc", then a request for /mypage would be directed to the module "abc_mypage".
module_aliases (proplist) - This provides the template system with a default list of module aliases to use within Nitrogen templates. (See the Template Element for more details).

    {sasl, [
        {sasl_error_logger, {file, "log/sasl-error.log"}},
        {errlog_type, error},
        {error_logger_mf_dir, "log/sasl"},      % Log directory
        {error_logger_mf_maxbytes, 10485760},   % 10 MB max file size
        {error_logger_mf_maxfiles, 5}           % 5 files max
    ]}

`etc/simple_bridge.config`

This file contains the configuration for SimpleBridge, Nitrogen's abstraction layer to each server. When you generate your initial Nitrogen release with rel_cowboy, rel_yaws, etc., Nitrogen will select the correct backend in this file for you.

backend (/Atom/ - cowboy | inets | mochiweb | webmachine | yaws) - This defines which backend SimpleBridge will use. It's set up by Nitrogen's release generation process. Note that if you change this value, you'll need to make sure you copy in the appropriate dependencies into the rebar.config file, as this toggle doesn't do it automatically.
handler (Module Name) - This is the name of the SimpleBridge handler that will deal with the request. In the case of Nitrogen, this should almost always be the atom 'nitrogen', which is a module in nitrogen_core.
bind_address (String) - The string or Erlang tuple of the IP address to bind. If set to "0.0.0.0", {0,0,0,0} or left blank, it'll bind to all available addresses. (Default: "0.0.0.0" )
port (Number) - The port number to bind. (Default: 8000)

About Ports and Linux: While port 80 is the standard HTTP port, port 80 is a privileged port in a Linux/Unix environment. This means that in order for Erlang to bind to port 80, it will need to be run with root privileges. This is generally unadvised. Instead, we recommend using a lightweight reverse proxy (such as nginx) in front of Nitrogen. Doing so will allow you to run Nitrogen with standard user privileges (for better system security), while presenting your Nitrogen website on the expected port 80.

On some variants of Linux, it is possible to bind Nitrogen to port 80 without running as root. This is accomplished with the use of the setcap application (which may need to be installed from your distro's package system).

An example of setcap being run on your Erlang app:
```
        sudo setcap cap_net_bind_service+ep ./erts-5.9.2/bin/beam
        sudo setcap cap_net_bind_service+ep ./erts-5.9.2/bin/beam.smp
```
This will give the beam and beam.smp programs privileges to bind to privileged ports (ports under 1024).
server_name (atom or string) - What to name the server. (Default: nitrogen)
document_root (String) - The root of the location of static resources (ie, stylesheets, javascript files, images, etc). This will be passed to simple_bridge for the serving of static files. (Default: "./site/static" )

Note: this is relative to the root of the Nitrogen installation.
static_paths (List of Strings) - The list of request paths which will automatically be handled by the static handler. Generally, this will be a list of directories (or files) within document_root provided above.

Consider the that your project as a priv/static directory has the following files:

favicon.ico (your site's favicon), js/ (a directory containing javascript files), css/ (a directory containing CSS rules).

You should have the following in your config:
```
    {document_root, "priv/static"},
    {static_paths, "favicon.ico", "js/", "css/"},
```
This will ensure that requests to (for example), "http://yoursite.com/js/my_javascript.js" gets handled by the server's static handler, and will be served from "priv/static/js/my_javascript.js"

Full configuration can be seen in Nitrogen's included simple_bridge.config or in SimpleBridge's sample config.

`plugins.config`

The Nitrogen plugin system is capable of automatically including plugin header files, along with importing static web resources (javascript files, images, etc). This can be done, and can be configured to work with just about any Nitrogen configuration, including non-standard configurations, such as manually importing Nitrogen as a dependency.

The plugins.config file contains information for how Nitrogen will import plugins.

It's a standard Erlang config file that takes three arguments.

plugins_hrl (path string) - Tell the Nitrogen plugin importer where to put the generated plugins.hrl file for the purposes of including plugin elements into your application. (default: "./site/include/plugins.hrl")
static_dir (path string) - Tell the plugin system where you wish to put your plugins' static resources. (default: "./site/static/plugins")
copy_mode (copy|link) - Tell the plugins system how to include any static resources. copy will copy the entire contents of your plugins' static directories, while link will merely create a symlink. If you work primarily with Linux or OSX, you can probably get away with using link, while if you use Windows, you should stick with copy. (default: copy).

Here's the complete text of the default plugins.config:

  %% vim: ts=2 sw=2 et ft=erlang
  %% Nitrogen Plugin Installer Configuration
  %%
  %% This will tell the plugin-installer script where to put Nitrogen plugin
  %% information it finds.
  %%

  %% plugins_hrl tells the Nitrogen plugin installer where to put the .hrl file
  %% containing links to all your plugins' respective header files.
  %% The default is "./site/include/plugins.hrl".
  {plugins_hrl, "./site/include/plugins.hrl"}.

  %% static_dir tells the Nitrogen plugin installer where to copy your plugins'
  %% static resources (images, js, etc).
  %% The default is "./site/static/plugins"
  {static_dir, "./site/static/plugins"}.

  %% copy_mode determines if static resources are copied or merely symlinked.
  %% Keep in mind, symlinks do not work on Windows, so "copy" is the default.
  %% Valid values are the atoms 'copy' or 'link'
  %% Default: copy
  {copy_mode, copy}.

More about Plugins

The plugin system has its own complete documentation along with a sample plugin stub for creating your own plugins.

We strongly advise reading the Plugin Documentation.

Notable mention: rebar.config

The standard for Erlang distribution and building is the use of Basho's rebar tool. Nitrogen takes advantage of this for simplifying the process of making releases and compiling Nitrogen even after a release is built and deployed.

Generally, the main reason one would want to customize their installation is by adding additional dependency packages. For example, if you wanted to include the erlware_commons package for improved date parsing and formatting, or the erls3 package to give your app an interface to Amazon S3, you would typically do it by adding the dependencies to rebar.config then running make in your Nitrogen installation.

By default, the only dependencies are the core dependencies for Nitrogen: nitrogen_core, nprocreg, sync, simple_bridge, and a webserver (Yaws, Cowboy, etc).

Also contained within the rebar.config are a handful of other compilation options: minimum Erlang version, where dependencies go, and debugging options.

Below is the rebar.config file when used with webmachine:

  {sub_dirs, [
      "site",
      "deps"
  ]}.

  {require_otp_vsn, "R13B04|R14|R15"}.

  {cover_enabled, true}.

  {erl_opts, [debug_info, fail_on_warning]}.

  {deps_dir, ["lib"]}.

  {deps, [
      {webmachine, "1.8.*", {git, "git://github.com/basho/webmachine.git", {tag, "webmachine-1.8.1"}}},

      {nitrogen_core, "2.1.*", {git, "git://github.com/nitrogen/nitrogen_core", "HEAD"}},
      {nprocreg,      "0.2.*", {git, "git://github.com/nitrogen/nprocreg", "HEAD"}},
      {simple_bridge, "1.2.*", {git, "git://github.com/nitrogen/simple_bridge", "HEAD"}},
      {sync,          "0.1.*", {git, "git://github.com/rustyio/sync.git", "HEAD"}}
  ]}.

To add the above mentioned dependencies (erlware_commons and erls3), edit the rebar.config file and modify the deps list to look like this:

  {deps, [
      {webmachine, "1.8.*", {git, "git://github.com/basho/webmachine.git", {tag, "webmachine-1.8.1"}}},

      %% Add our two new dependencies below
      {erls3, "1.9.*", {git, "git://github.com/shane42/erls3.git", "HEAD"}},
      {erlware_commons, ".*", {git, "git://github.com/erlware/erlware_commons.git", "HEAD"}},

      {nitrogen_core, "2.1.*", {git, "git://github.com/nitrogen/nitrogen_core", "HEAD"}},
      {nprocreg,      "0.2.*", {git, "git://github.com/nitrogen/nprocreg", "HEAD"}},
      {simple_bridge, "1.2.*", {git, "git://github.com/nitrogen/simple_bridge", "HEAD"}},
      {sync,          "0.1.*", {git, "git://github.com/rustyio/sync.git", "HEAD"}}
  ]}.

Then run make from the root of your Nitrogen installation. This will download the new dependencies and install them into the lib directory of your installation.

Server-specific Configuration (Cowboy, Yaws, etc)

If you're running an older version of Nitrogen (pre-2.3) or you're running a Nitrogen without using the standard simple_bridge config, you can check out the server-specific configuration options (no longer maintained), otherwise, you'll have to look at the server's official documentation.

Additional Configuration

Smart Extensions

See Smart Extensions Documentation

nginx - A lightweight reverse proxy

Nginx is high performance, lightweight web server and reverse proxy that is commonly used for load balancing, rewrite rules, SSL certificates, and more.

Here's a sample configuration (this assumes a standard Ubuntu configuration):

/etc/nginx/nginx.conf

  user www-data;
  worker_processes  1;

  error_log  /var/log/nginx/error.log;
  pid        /var/run/nginx.pid;

  events {
              worker_connections  4096;
  }

  http {
          include       /etc/nginx/mime.types;
          default_type  application/octet-stream;

          access_log      /var/log/nginx/access.log;

          sendfile        on;

          keepalive_timeout  10;
          tcp_nodelay        on;

          gzip  on;

          proxy_set_header X-Forwarded-Host $host;
          proxy_set_header X-Forwarded-Server $host;
          proxy_set_header Host $host;
          proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;


          include /etc/nginx/conf.d/*.conf;
          include /etc/nginx/sites-enabled/*;
  }

Non-SSL Sample: /etc/nginx/sites-enabled/my_site

  server {
          listen   80;
          server_name  mysite.com www.mysite.com;
          access_log  /var/log/nginx/mysite.com.access.log;
          location / {
                  proxy_pass http://127.0.0.1:8000;
          }
  }

SSL-Only Sample: /etc/nginx/sites/enabled/my_secure_site

This configuration will server only SSL. It will redirect all requests from the HTTP port (port 80) to the HTTPS port (port 443) and load the certificates

  # My config for a site that I only want serving SSL content.
  server {
          listen   80;

          server_name www.mysite.com, mysite.com;
          access_log  /var/log/nginx/mysite.com.access.log;

    # rewrite all requests to be SSL
          rewrite ^(.*) https://$host$1 permanent;
  }

  server {
          listen 443;
          server_name mysite.com www.mysite.com
          access_log /var/log/nginx/mysite.ssl.access.log;

          ssl on;

          ssl_certificate ssl/mysite/mysite.com.crt;
          ssl_certificate_key ssl/mysite/mysite.com.key;
          ssl_client_certificate ssl/mysite/ca.crt;

          location / {
          # This installation is running on port 8021, as you can plainly see.
            proxy_pass http://127.0.0.1:8000;
          }
  }

View Source or Submit Corrections for this Documentation Page

Released under the MIT License.