Getting Started

Prerequisites

Node.js v4 or v5 is recommended. Consider using a tool like nvm to install and manage Node installations.

Installing

Once you have Node and NPM installed, first create a directory for your application.

$ mkdir myapp
$ cd myapp

The easiest way to get started with BlueOak Server is to install it globally through NPM.

$ npm install -g blueoak-server

You can test your installation by running the blueoak-server command in a shell.

$ blueoak-server
info: index.js - Starting blueoak-server v2.0.0 in development mode using Node.js v4.2.4
info: index.js - Clustering is disabled
info: monitor - Monitoring is disabled.
info: auth - Starting auth services
info: express - App is listening on http://:::3000
info: blueoak-server.js - Server started

A server is now running on port 3000. However, since you haven't yet defined any content, you'll get an error message if browsing to http://localhost:3000.

Hit Ctrl+C at any time to stop the server.

Defining configuration

The first thing we want to do is create a config file. From the config, we can control things like which port the app runs on, or which middleware to load.

Let's create some config and change the port from the default of 3000 to 8080.

$ mkdir config
$ touch config/default.json

Configuration in default.json will always be loaded regardless of the environment.

Open the default.json and set the content as follows:

{
  "express": {
    "port": 8080
  }
}

Run the blueoak-server command again and see that the server is now listening on port 8080.

$ blueoak-server
info: index.js - Starting blueoak-server v2.0.0 in development mode using Node.js v4.2.4
info: index.js - Clustering is disabled
info: monitor - Monitoring is disabled.
info: auth - Starting auth services
info: express - App is listening on http://:::8080
info: blueoak-server.js - Server started

Creating a Handler

Handlers are used to create REST endpoints for the application. While we encourage the use of Swagger to define endpoints, it is possible to create endpoints in a typical Express fashion.

First create a handlers directory and a handler file.

$ mkdir handlers
$ touch handlers/myhandler.js

Set the content of myhandler.js as follows:

exports.init = function(app) {
        app.get('/', function(req, res) {
                res.send('Hello World!');
        });
}

Start the server again. Now if you browse to http://localhost:8080/, you'll be greeted with the text "Hello World!".

If you've used Express before, this will seem familiar. However, let's examine what's different. First, rather than having to explicitly require the express and initialize the app, blueoak-server did this for you.

The init module that your handler exports tells the server to run the code at startup. The app parameter is a reference to the Express app which is dependency-injected into the function. The app isn't the only parameter you can inject into your function. BlueOak has the concept of a service, and any service that exists can be injected. You can create your own services, or use a built-in service like the logger.

You also didn't have to call app.listen. BlueOak starts listening for you. And instead of having to hardcode a port value into your code, it's configured through the config file you created earlier.