---
title: "Module Installation"
description: "Optimize your Node.js app with Cloud CMS, featuring custom modules, configurations, and extensibility for enhanced functionality. (Gitana 4.0)"
product: "Gitana"
version: "4.0"
url: "/documentation/gitana/4.0/developers/app-server/installation/module"
---

# Module Installation

The Cloud CMS Application Server can also be run as a custom Node.js application. It is available as a Node.js module that you can `require()` in from npmjs.org. The server features a number of extension points that you can utilize to wire in new functionality or extend the framework.

## Getting Started

Here is a simple example where we start up the Application Server from within a Node.js application:

```
var server = require("cloudcms-server/server");
server.start();
```

The `start()` method takes an optional configuration object as an argument that can be used to configure and set up the features and services available within the framework.

```
// start up the server with wcm (web content management) enabled
var server = require("cloudcms-server/server");
server.start({
    "wcm": {
        "enabled": true
    }
});
```

## Configuration

You need to tell the Cloud CMS Application Server about your Cloud CMS account. Specifically, you will need to go into your Cloud CMS tenant's user interface and create a Project. A Project is where you store all of your content.

Within your Project, create an Application. The Application will come with a `default` deployment and a default set of API Keys. You can access these API Keys from the "API Keys" navigation item on the left-hand side of the page.

![apikeys1.png](/documentation/gitana/4.0/developers/app-server/installation/module/apikeys1.png)

Click on `gitana.json` to view the keys.

![apikeys2.png](/documentation/gitana/4.0/developers/app-server/installation/module/apikeys2.png)

Copy and paste the contents to a file called `gitana.json` in the current directory. The `gitana.json` file should sit alongside the `app.js` file.

### Customize the Express App

When the server instance starts up, it calls through a chain of configuration functions that are able to configure the underlying Express `app` instance.

You can register a configuration function using the `configure(function(app, callback) { })` method. The `callback` _must_ be fired once your code completes.

```
server.configure(function(app, callback) {
    
    // set up the app instance
    app.abc = 123;
    
    // fire the callback
    callback();
});
```

### Customize Web Sockets

If you've enabled web sockets, then the underlying socket.io connect event will fire for every browser or mobile app connection that is started up. You can use the `sockets(function(socket, callback) { })` function to configure sockets before they are used.

The `callback` _must_ be fired once your code completes.

```
server.sockets(function(socket, callback) {

    // send a hello message to the client
    socket.emit("hello", {
        "message": "Hello World"
    });
    
    // fire the callback
    callback();
});
```

### Customize Routes

The `routes(function(app, callback) { })` function provides a place where you can register conventional Express routes. These include handlers for GET and POST method calls and so forth.

The `callback` _must_ be fired once your code completes.

```
server.routes(function(app, callback) {
    app.get("/hello", function(req, res) {
        res.send("Hello World").end();
    });
    callback();
});
```

### Customize Driver

The `driver(function(app, callback) { })` function provides a place where you can register functions that can dynamically set the `req.gitanaConfig` driver configuration that will be used by the framework. By setting this variable to your desired driver configuration, the driver will automatically be connected and methods such as `req.branch()` will be available to middleware functions downstream.

The `callback` _must_ be fired once your code completes.

Here is an example where we might have two driver configuration files on disk (`gitana1.json` and `gitana2.json`) and we pick one based on a request parameter:

```
server.driver(function(app, callback) {

    app.use(function(req, res, next) {

        var preview = req.query["preview"] === "true";
        var filename = (preview ? "gitana2.json" : "gitana1.json");

        req.gitanaConfig = JSON.parse("" + fs.readFileSync("./" + filename));

        next();
    });

    callback();
});
```

## Customize Dust

The Application Server uses the LinkedIn Dust.js engine to provide layouts, templating and component rendering. You may wish to register custom Dust handlers or customize the Dust engine. Use the `dust(function(app, dust, callback) { })` function to customize Dust before it is used.

The `callback` _must_ be fired once your code completes.

Here is an example where we register a new `@sample` helper Dust tag.

```
server.dust(function(app, dust, callback) {

    // utilities
    var support = require('cloudcms-server/duster/support')(dust);
    var end = support.end;

    // sample dust helper
    dust.helpers.sample = function(chunk, context, bodies, params)
    {
        return support.map(chunk, function (chunk) {
        
            // message
            var message = context.resolve(params.message);

            // write and end this chunk
            chunk.write(message);
            end(chunk);
        });
    };

    callback();

});
```

This helper function can then be used within your HTML pages like this:

```
{@sample message="Hello World" /}
```

## Before Server Startup

Use the `before(function(app, callback) { })` method to provide handlers that should run _before_ the server binds to the port (i.e. before the server comes online).

The `callback` _must_ be fired once your code completes.

```
server.before(function(app, callback) {
    console.log("The server is about to start!");
    callback();
});
```

## After Server Startup

Use the `after(function(app, callback) { })` method to provide handlers that should run _after_ the server has started. This code runs once the port has been bound and the server is handling requests.

The `callback` _must_ be fired once your code completes.

```
server.after(function(app, callback) {
    console.log("The server has started!");
    callback();
});
```

### Post Startup Report

Depending on how you have things set up, the server will start up either on a single CPU or on multiple CPUs using the Node.js `cluster` module. If started on multiple CPUs, the `before` and `after` methods will run once per CPU. This means that the "The server has started!" message from above may print multiple times - once per CPU.

In some cases, you may wish to provide a callback that only runs once all of the servers have started on all of the available CPUs. Use the `report(function(callback) { })` method to register a callback that will be fired exactly once when all servers are online.

This is frequently useful for reporting and/or logging the startup of your server. Hence the name!

The `callback` _must_ be fired once your code completes.

```
server.report(function(callback) {

    var cpuCount = require('os').cpus().length;

    console.log("Hello World - running on: " + cpuCount + " cpus");

    callback();

});
```

## Store Values

The server object provides `get` and `set` methods for storing key/value pairs on the server instance. You can use this as you wish and as a means for retrieval later within custom services.

```
// set a value onto the server
server.set("host", "http://www.cnn.com");

// get a value from the server
var host = server.get("host");
```

## Error Pages

If something goes wrong within any of the interceptors or handlers in the request processing chain, an error will be thrown. You can register error pages to handle these errors and produce meaningful messaging to your front end users about what went wrong.

```
server.error(function(app, callback) {

    // send a 503 back to the user
    app.use(function(err, req, res, next) {
        res.status(503);
        res.send("Phooey. An error occurred: " + err.message);
    });

    callback();
});
```

If you don't provide any custom error pages, the server will default to using the default error page for Node Express. This shows a stack trace and a print out of what went wrong.
