sn-app/README.md

Node.JS App Accelerator - Build a skeletal web app using connect / mysql / mongodb in seconds

sn-app
==========

Simple app framework for Node.JS apps.

# Introduction

sn-app uses the sn-props package to read global properties for a node
app. It then initializes various services based on the props file
contents.

The objective is to move the initialization of services from code to a
declarative properties file so an application's config state can be
easily stored in a file or http resource.

The benefits include:

1. Moving app configuration information from environment variables into JSON files.
1. Many configuration changes (moving from connect to express, changing database references, including various packages) require changing a config file, not a code change.

# Installing

Sn-app generally requires either connect.js or express.js to function properly.
But we don't know which one you're going to use, so it's up to you to explicitly
install them. Fortunately, it's easy to do this with npm. So if you were going
to use connect, you would use this npm command:

<pre>    npm install sn-app connect</pre>

If you were going to use express.js, you would use this npm command:

<pre>    npm install sn-app express</pre>

If your application uses the Sn-logger or Sn-persist packages, you'll
have to manually install these as well.

If you want to install the package with git, run make after you clone
the repo to install sn-props as a dependency.

<pre>    git clone git@github.com:smithee-us/sn-app.git; cd sn-app; make</pre>

# Usage (Simple)

The simplest way to use sn-app is to use the 'sn-app' command, passing
it the name of one or more configuration files:

<pre>sn-app --config file://production.json</pre>

This usage uses the node-props package to read the configuration file
("production.json" in this case) and start a node service based on the contents
of the config file.

Here's a very simple configuration file:

<pre>{
  "favicon": "static/favicon.ico",
  "access": {
    "path": "logs/sample_access.csv",
    "format": "\":date\",\":req[x-forwarded-for]\",\":method\",\":status\",\":req[host]\",\":url\",\":referrer\",\":user-agent\""
  },
  "static": {
    "path": "static",
    "maxAge": 14400000
  },
  "listen": {
    "port": 8080
  }
}</pre>

This config file would start a connect.js server, calling use() with parameters
appropriate to:

* setup a static file store in the 'static' directory
* open an access log in the file 'logs/sample_access.csv'
* use favicon.ico as the site's icon
* and finally, listen on port 8080 on all interfaces.

A complete guide to sn-app config file parameters are provided below.

## Using sn-app when the package is installed globally

It's not uncommon for people to install <code>sn-app</code> globally, but install
dependent packages in a local directory. In other words, you might try something
like this:

<pre>    sudo npm install -g sn-app
    mkdir test-sn-app
    cd test-sn-app
    npm install connect sn-logger</pre>

This will work fine as long as you set the <code>NODE_PATH</code> environment
variable to tell node where to find the local packages you've installed. (By
default, it looks for them near where the sn-app binary is installed, which
is not your local directory.) Doing something like this should avoid the
problem:

<pre>    export NODE_PATH=`pwd`
sn-app --config file://properties.json</pre>


# Usage (More Complex)

The sn-app package includes a "plain 'ol package" you can use in your own
code in case you want to extend it or grab the config file from somewhere other
than the command line.

Here's an example of it's use:

<pre>var app = require( 'sn-app' );
var props = require( 'node-props' );

console.log( "Reading configuration file(s)." );

props.read( function ( g ) {
  console.log( "Initializing application." );
  var server = ( new app( g ) ).init( function ( err ) {
    if( err ) {
      throw err;
    }
    console.log( "Listening on port " + g.listen.port );
    server.listen();
  } );
} );</pre>

There are really only three public methods for sn-app: the constructor,
init() and listen().

* new app() - You create a new application instance in the traditional manner
by calling it's constructor, passing the configuration object (described below)
as a parameter.
* init() - This method parses config object, creating appropriate instances
of objects and calling use() when needed. It does just about everything you
need to do save calling the listen() method. Keep in mind this can involve I/O,
so you need to provide a callback function to be executed after initialization.
* listen() - This method calls the listen() method on all servers defined in
the config object.

# Config File / Object Reference

## Basic Configuration Properties

*engine* - "connect" or "express"

sn-app can use either connect.js or express.js as a base to build a server.
By default, connect is used.

*bodyParser* - false

If the bodyParser property is present in the configuration option and is set
to a non-false value (like the boolean true value), the connect.js bodyParser
middleware will be used.

*cookieParser* - true or string

If the cookieParser property is present and set to a non-false value, the
cookieParser middleware will be used. If the property's value is a string,
it will be passed to the connect.cookieParser() call as the "optional secret
string" parameter.

*favicon* - string

This property tells sn-app to use the connect.favicon() middleware. It's
placed before the access middleware, so favicon requests will not appear in
the access log.

*static* - string or object

If this property is present, it is either that name of a directory containing
static files to serve up. Or it is an object passed to the connect.static()
middleware.

*errorHandler* - object

If present, it is passed to the connect.errorHandler() middleware.

*listen* - object

This object contains the port and host properties which are used to determine
the port and IP address to listen on.

Here's an example of an extremely basic configuration that uses connect.js to
listens on port 8080, serving files out of a directory called "public":

<pre>{
  "static": "public",
  "listen": {
    port: 8080
  }
}</pre>

## Express.js properties

These config properties are useful only when using express.js as your engine.

*views* - object

This property contains an object with "path" and "engine" properties. The
path proerty describes where the view templates will be located while the
engine property identifies which engine ("hbs", "jade", etc.) to use.

*router* - true

If this property is present, it causes the express router middleware to be
used. This is the equivalent of calling <code>app.use( app.router );</code>.

## sn-app properties

These properties are used to configure sn-app's "advanced" features:

*persist* - object

If present, the sn-persist package will be required and this property,
which describes database options will be passed to it's constructor.

*logger* - object

If present, causes the sn-logger package to be required. This property
will be passed to the sn-logger constructor.

*access* - object

If present, it creates an instance of the connect.js logger() object using
the "format" property. If the path property is present, a file stream will
be opened and passed to the logger() constructor.

*templates* - string

This property is the path to the templates directory. If present, the system
will scan the directory for HTML fragments, and making them available to
web clients as '/templates.json'. It is intended to be an easy way to deliver
a large number of HTML templates in one request.

*source* - string or object

If present, the file (or files) referenced will be required and called passing
the facilities object and the application's defaults.

*apps* - object

To start multiple servers listening on different ports, include an apps property
whose value is an object whose properties are app descriptors.

*start* - object

By default sn-app starts all servers described in the apps section. If this
array of strings is present, only those servers listed here will be started.

Here's an example:

<pre>{
  "persist": {
    "log": {
      "level": 1
    },
    "providers": {
      "localdb": {
        "host": "localhost",
        "database": "testing",
        "user": "testuser",
        "password": "as if i would list a password here"
      },
      "collections": {
        "identity": "collection_identity",
        "session": "collection_session"
      }
    }
  },
  "logger": {
    "facility": "EXAMPLE",
    "messages_path": "example_messages.json"
  },
  "start": [ "main" ],
  "apps": {
    "main": {
      "template": {
        "path": "templates"
      },
      "access": {
        "path": "logs/main_access.csv",
        "format": "\":date\",\":req[x-forwarded-for]\",\":method\",\":status\",\":req[host]\",\":url\",\":referrer\",\":user-agent\""
      },
      "static": {
        "path": "static",
        "maxAge": 14400000
      },
      "listen": {
        "port": 8080
      }
    },
    "admin": {
      "template": {
        "path": "admin/templates"
      },
      "access": {
        "path": "logs/admin_access.csv",
        "format": "\":date\",\":req[x-forwarded-for]\",\":method\",\":status\",\":req[host]\",\":url\",\":referrer\",\":user-agent\""
      },
      "static": {
        "path": "admin/static",
        "maxAge": 14400000
      },
      "source": "src/logic_admin",
      "listen": {
        "port": 8085
      }
    }
  }
}</pre>