paasmaker-interface-nodejs / README.md

Paasmaker node.js interface

This is a helper library for node.js applications deployed with Paasmaker.

You can read more about the Paasmaker platform as a service at www.paasmaker.org.

To install

Simply use npm:

$ npm install paasmaker

Source code for the library is on BitBucket and GitHub.

In your application

Require the library and then create an instance:

var paasmaker = require('paasmaker');

var pm = new paasmaker();

The new instance has a few important methods and properties, listed below.

isOnPaasmaker()

Returns true if the application has been started by Paasmaker, i.e. configuration details are in the environment variables.

getPort()

The port number that your application should listen on. This is assigned to your app by Paasmaker's router so it doesn't conflict with other running apps.

(As well as this getter function, the property port can also be used.)

getAllServices()

Returns a hash of connection information returned by Paasmaker service plugins (databases, caches, etc.). You can also use the method getService(name) to return data on one particular service.

For example, if you have the mongoDB plugin enabled, the returned object might look like this:

{
    "mongodb": {
        "hostname": "192.168.0.1",
        "port": 1234
    }
}

Application metadata

There are several getter functions for generic metadata about Paasmaker's record of your application. For example, if your code is deployed as version 7 of an application called TestApp in a workspace called Test Workspace:

pm.getApplicationName();    // returns "TestApp"
pm.getApplicationVersion(); // returns 7
pm.getWorkspaceName();      // returns "Test Workspace"
pm.getWorkspaceStub();      // returns "testworkspace"

Local development with configuration files

For local development (not running on Paasmaker), you can provide an array of file paths to the paasmaker() constructor. Each path will be tried, and the first file that exists will be loaded.

Config files should be in JSON format with properties for port, service details, and application metadata:

{
    "services": {
        "foobar": {
            "foo": "bar"
        }
    },
    "application": {
        "name": "test",
        "version": 1,
        "workspace": "Test",
        "workspace_stub": "test"
    },
    "port": 12345
}

Alternatively, consider setting up a local instance of Paasmaker and using the development directory plugin.

Example application

var http = require('http');
var paasmaker = require('paasmaker');

var pm = new paasmaker();

if (!pm.isOnPaasmaker()) {
    throw new Error("Can't run, we're not deployed on Paasmaker!")
}

http.createServer(function (req, res) {
  res.end("Hello world! From " + pm.getApplicationName(), 'utf8');
}).listen(pm.port);

Errors

Because error handling in Node is complicated, we've taken the simple way out of just throwing exceptions. Since the environment variables with configuration details are always set by Paasmaker, you're most likely to see exceptions in outside development where you've forgotten to set config files.

License

This interface library is released under the MIT License. Paasmaker itself is licensed under the MPL v2.

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.