Table of Contents

Introduction

Welcome to the Nodejitsu handbook. This document will help familiarize you with
deploying your Node.js applications to the cloud while also providing
detailed information about Nodejitsu's platform-specific features and about
where to get help when you need it.

Who Is Nodejitsu?

We are a collection of seasoned developers who have been devoted to the Node.js
community since 2009. We are community leaders who have created and contributed to
hundreds of open-source Node.js projects. If you have used Node.js, you've
probably used some of the projects we've helped create.

What Is Nodejitsu?

Nodejitsu is a Platform as a Service and a Marketplace
for Node.js applications. Nodejitsu allows you to seamlessly deploy your Node.js
applications into the cloud with a myriad of additional features. Our platform
provides a robust suite of functionality to assist in the development,
management, and deployment of Node.js applications. Our deployment tools are the
most user-friendly in the industry and our customer support is unparalleled.

Getting Started

So you wish to learn the ways of Nodejitsu? Excellent! You only need to know
three things to get started:

We're Nodejitsu, and we can give you scalable,
fault-tolerant cloud hosting for your Node.js apps - and we're the best you'll
find.

Hello World: A Tutorial

In this tutorial, you will write a simple "hello world" web application in
Node.js, and then deploy it using jitsu, Nodejitsu's command line interface.

Before you get started, you should have
node.js installed. If you are using
a node.js version older than v0.6.0 (not recommended) you will also need to
separately install
Node Package Manager (npm).

Write A Server:

Let's start with a very basic Node.js http server. Create a folder called
myapp/ and then create a file inside the folder called server.js. Inside
this file, write the following code:

// requires node's http module
var http = require('http');
// creates a new httpServer instance
http.createServer(function (req, res) {
// this is the callback, or request handler for the httpServer
// respond to the browser, write some headers so the
// browser knows what type of content we are sending
res.writeHead(200, {'Content-Type': 'text/html'});
// write some content to the browser that your user will see
res.write('<h1>hello, i know nodejitsu.</h1>');
// close the response
res.end();
}).listen(80); // the server will listen on port 80

That's all the code you'll need for starters. Save your server and get ready to
deploy!

Deploy with Jitsu:

In this tutorial, we will use jitsu to deploy
our "hello world" application. Jitsu is a
Command Line Interface
for using Nodejitsu's platform. We've designed jitsu to be
suitable for command line beginners, but still be powerful and extensible
enough for production usage. If you aren't a fan of the command line or don't
have terminal access you can still do app deployments through the
Nodejitsu Web Application.

If this is your first time deploying an application and you are eager to get
started, we recommend using jitsu: it has a one line installer, it's
self-documenting, and with it you'll be able to deploy your app in seconds.
Plus, it's what's in the tutorial.

Installation

In order to install jitsu, open a terminal and type:

[sudo] npm install -g jitsu

This command will install jitsu on your system; the -g makes npm install it
globally, rather than a local module.

After installation, run the jitsu command from your command line. Since it's
your first time using jitsu, you will be prompted to log in with an existing
account or to create a new account.

Once you've logged in, you can deploy your app immediately.

One Line Deployment

Open a terminal:

cd /home/me/myapp
jitsu deploy

This will create a new application snapshot, generate and/or update project
metadata, and deploy the project in the current path to
Nodejitsu. If it's your first deployment, you'll be
prompted for some information such as your app's name, its
nodejitsu subdomain, and its start script. It's really easy and we promise it will
only take a few seconds.

Now just open up your favorite browser, and go to
yoursubdomain.nodejitsu.com. If everything has been set up correctly, then
you, too, are on the path of nodejitsu!

Features of the Nodejitsu Platform

The Nodejitsu platform makes writing and deploying web applications a snap!
In addition to simple yet powerful tools for deployment, the Nodejitsu platform
also has snapshot management, database hosting and connectivity, and more!

Each of these tools allow developers to access the exact same functionality.

Multi-Version node support

Nodejitsu allows users to choose which version of node they want their application to run on. This means that not only do we now support v0.6, but also that users may continue to use v0.4 if they would like.

In order to set your node version, specify it in your package.json's "engines" field. For example:

Snapshots

Every time you deploy to Nodejitsu, we automatically take a
snapshot of your
application. Using any of our tools, you can view and manage snapshots, or even
roll back to an old snapshot when disaster strikes in your production
environment.

Databases

Applications on Nodejitsu are ready to be connected to any database. If you already have a database running, Nodejitsu can connect to your pre-existing database. If you require a new database, Nodejitsu can provide you free instances of several different types of databases. These free instances are great for development purposes or hobby sites. If you require a high traffic or production database we provide an easy upgrade path to industrial strength database hosting.

Creating new Databases

If you require database hosting you can create a new database instance of any
of our supported databases using jitsu or Nodejitsu's API. Cloud database hosting is currently provided by IrisCouch, Redis2Go and MongoHQ.

Existing Databases

If you already have an externally hosted Database, Nodejitsu is capable of
connecting to it. We've got Database hosting if you need it, but we fully
support externally hosted Databases.

Connecting Applications to Databases

Whenever you create a database using Nodejitsu, you will be provided with all
the information you need to connect to your database. For instance, if you
jitsu databases create mongo myMongo, jitsu will tell you the url for your new
mongo database on mongohq:

Environment Variable Management

Nodejitsu allows users to modify the environment variables exposed to their
apps using jitsu and our other tools. When an environment variable is changed
it is necessary restart your app for it to take effect.

Available commands are list, get, set, delete, and
clear.

jitsu env list will list any and all environment variables in an apps
current working directory (Note: the app needs to have been deployed before the
environment variables can be accessed).jitsu env list <myapp> will list any and all environment variables related
to <myapp> in an account.jitsu env get <key> will display the apps key environment variable
<value>.jitsu env set <key> <value> will set the apps <key> environment variable
to <value>.jitsu env get <key> will delete the apps <key> environment variable.jitsu env clear will delete all of the apps environment variables after a
prompt.

An Example:

$ jitsu env set NODE_ENV production

This will set the environment variable $NODE_ENV to have the string value
"production". Remember, this will not take effect until the app is restarted
(jitsu apps restart).

Addons

Note: Coming soon!

Addons add functionality to your apps by extending and adding features to
Nodejitsu's platform and integrating third party services. For instance,
one of our addons provides powerful Mailchimp-based
mailing list management.

Marketplace

Note: Coming soon!

The Marketplace is an online store where you can browse ready to deploy
Node.js Applications. The Marketplace is a great place to start if you are new
to Node.js development or want to share your existing Node.js Application with
the world.

jitsu list (jitsu apps list)

jitsu help

Jitsu is self-documenting.
All commands will yield friendly messages to you if you specify incorrect
parameters. Additionally, jitsu help will return useful help messages about
any given resource or resource/action pair. for instance:

If no resource and/or action are specified, then jitsu help alone will
describe what resources are available.

jitsu apps

In addition to the commands aliased to jitsu create, jitsu deploy and
jitsu list, the apps resource allows you to create, destroy, stop, start and
otherwise interact with your applications.

jitsu env

Jitsu allows you to set environment variables on your production environment.
For example, Express, a popular node.js web framework,
uses the NODE_ENV environment variable to change behavior based on whether the
environment is for development or production. In the case of Express, nodejitsu
has NODE_ENV set to "production" by default, but if one wanted to change this
variable or add more for their application, jitsu env supplies the tools to
do so.

Configuring jitsu

All user-level configuration data for your local jitsu install is located in the .jitsuconf file located in your home directory. Directly modifying this file is not advised. You should be able to make all configuration changes using jitsu config.

Selected Properties of .jitsuconf

loglength: Change this to modify the default length of returned logs from jitsu logs.

loglevel: Change this to modify the logging levels displayed by jitsu. Defaults to "info".

colors: Change this to false to turn off jitsu's colors. Defaults to true.

analyze: Change this to false to disable require-analyzer for all apps. Defaults to true.
# Nodejitsu Web Application

The Nodejitsu Web Application allows developers to administrate their
applications through a web interface. This interface allows access to the same deployment functionality that can be found in jitsu or the JSON API.

JSON API

Nodejitsu provides a web API for developers who want to interact with the
Nodejitsu platform programatically. This API is built to be
RESTful and
communicates via JSON. The API is the most
low-level way of interacting with the Nodejitsu platform. For most deployment
scenarios you should use our command line tool, jitsu, or the
online administrative interface.

API Clients

Nodejitsu has a JSON API client for node.js, which may be found here (along with API clients in other languages as they are developed). Jitsu is implemented by using the node.js API client.

Authentication

Most of the calls to the API will require that you authenticate using your Nodejitsu account. If you do not have an account it is possible to create one using the API, the jitsu CLI, or just by visiting http://nodejitsu.com. Currently, we support Basic Authentication. If you haven't used Basic Auth before, don't fret; it's easy!

Applications

Applications are the core of the Nodejitsu API. Each application represents a set of Node.js code plus a package.json which contains meta-data about the application such as it's dependencies, database connections, configuration settings and authors. For more information about the package.json format see: package.json

Get all Applications for a User

GET /apps/:user-id

Create a new Application

POST /apps/:user-id
{ package.json }

Start an Application

POST /apps/:user-id/:app-id/start

Stop an Application

POST /apps/:user-id/:app-id/stop

Restart an Application

POST /apps/:user-id/:app-id/restart

Update an Application

PUT /apps/:user-id
{ package.json }

Delete an Application

DELETE /apps/:user-id/:app-id/remove

Snapshots

Make an existing snapshot the active app

POST /apps/:user-id/:app-id/snapshots/:id/activate

Activate / Deploy a snapshot

POST /apps/:user-id/:snapshots/:id

Show a catalog of all Snapshot for an Application

GET /apps/:user-id/:app-id/snapshots

Show the contents of a Snapshot

GET /apps/:user-id/:app-id/snapshots/:id

Users

Create a new User / Sign-up for a free Nodejitsu account

Email address is the only required field.

POST /users/:user-id
{
email: "youremail@theinternet.com"
}

Confirm a User account

All User accounts must be confirmed. When a new User is created, a confirmation email will be sent to the email address associated with that user. In this email there will be an invite code. This code must be sent to the API to confirm the account.

Update User

Databases

Create a new Database

Get information about a Database

GET /databases/:user-id/:database-id

Delete a Database

DELETE /databases/:user-id/:database-id

Logging

Logging is a very important feature in any professional grade Node.js
application. Nodejitsu provides integrated logging solutions for your
applications. Your logs are always saved and ready to be retrieved.

Get all logs for a user

Get logs for a specific application

Marketplace

Get all Marketplace Applications

GET /marketplace

Get a specific Marketplace Application

GET /databases/:user-id/:id

Create Your Own Cloud With Haibu

Haibu is an open-source tool for spawning and managing several node.js
applications on a single server. It's an integral part of Nodejitsu's
production stack and is fully supported by a dedicated team of core node.js
developers.

By installing haibu, a user creates a development environment for themselves
that mirrors the functionality of Nodejitsu's cloud platform! Any project that
can be deployed on Nodejitsu can be ran by haibu.

Haibu, which is Japanese for "hive", wraps node.js applications in a "carapace"
and converts them into managed "drones". This approach allows haibu to directly
interact with node.js applications and add all sorts of additional
functionality. Haibu also contains a plugin system, so you can easily add even
more functionality.

Haibu builds on this concept of "drones" and exposes a robust and granular API
for interacting with your node.js applications. At a low level, haibu's API is
exposed as a RESTFul HTTP webservice. Any system that supports basic HTTP
requests can communicate with a haibu server. If you are working in Node.js,
haibu comes with a high-level Node.js API client.

Installation

[sudo] npm install -g haibu

This will install haibu globally.

Usage

Haibu comes with three applications, one of which is optional:

haibu-server is the program that manages your node.js web applications.
Haibu-server allows you to manage and track your drones.

haibu is the user interface for interacting with (and administrating) a
running haibu-server.

haibu-balancer [optional] is a load balancer tool, used to split
requests across multiple drones of the same application. It is entirely
optional, and many deployments won't have a need for it.

It may be nice to flesh this out with an example deployment, but I think this
should be relatively low priority.

Additional Documentation

Open Source Projects

Why Open Source

Most of Nodejitsu's technology stack is released as open source software. We
choose to do this for many reasons. Aside from being able to give back to the
Node.js community, releasing pieces of our stack as open-source allows other
developers to review and improve our software. We've already received invaluable
contributions to our platform from developers who would have never seen our code
if we had not open-sourced it.

Github is a web site for sharing and
collaborating on source code using git, a popular version
control system. You can get our source code without creating an account at
github, and if you want to create an account it's free. You will need a
git client if you wish to clone any of our
code repositories.

How To Contribute

Anyone can contribute to any of our open-source projects at any time.
Our github site has the facilities for managing
patches, issues, code comments, version control, and just about anything else an
open source developer could need.

Frequently Asked Questions

"How do I reset my password?"

One way is to use jitsu. Simply type:

jitsu users forgot :username

where :username is your username. Alternately, go to http://develop.nodejitsu.com/ and click the "forgot password" link, where you will be prompted for your username. Either process will send you an email with further instructions.

"Is there a cheatsheet somewhere?"

"How are programs kept alive? Do I need to use Forever?"

Nodejitsu's cloud services watch your programs for you! You shouldn't have to do anything special to keep your apps running, much less use Forever.

"How can I make my app use a port other than port 80?"

Connecting to other servers using arbitrary ports requires no special considerations. However, listening for outside connections is currently limited to port 80 on the Nodejitsu platform because we require http host headers for domain name resolution of subdomains. Consequentially, each subdomain may only host one listening service.

The ability to host tcp applications on nodejitsu and listen on non-80 ports is on our roadmap but has no associated timeline.

"How can I point my custom domain to my nodejitsu app?"

"How can I turn off the require-analyzer in jitsu? I want to manage my own dependencies!"

There are three ways to disable the require-analyzer:

Use the --noanalyze flag when running jitsu commands to disable it on a one-time basis.

Add "analyze": false to your package.json to disable it on a per-app basis.

Set "analyze" to false in your ~/.jitsuconf to disable it on a global level.

"Why won't this C++ addon compile?"

Many C++ addons require libraries that are not included in Nodejitsu's infrastructure by default. For example, node-canvas requires cairo, which only recently became available on nodejitsu's platform.

"How do I specify which files not to bundle? How do I know what files are getting bundled?"

Jitsu uses npm to bundle files, meaning that jitsu bundles files in exactly the same manner than npm bundles published modules. You can read about this in npm's documentation.

In more detail: npm uses a file called .npmignore, which should contain a list of files and folders to ignore for the purpose of bundling. If this file does not exist, npm will use git's ignore file, called .gitignore, instead. This means that, if you want to bundle files that are ignored by git, you should create an .npmignore even if it's blank.

Finally, jitsu has the ability to bundle your app without deploying with the jitsu package create command. You can use this to make sure that the resulting .tgz file is as you expect.

Support

Nodejitsu has a team of developers standing by to assist users with any issues
they may come across while deploying and administrating their web applications
on the Nodejitsu platform. Nodejitsu strives to have a lightning-fast
turnaround on all issues you may have!

bug.jit.su / E-mail

http://bug.jit.su/ is a webapp we built for users to submit bugs and/or
problems(Recommended). You can also contact us via email, at
support@nodejitsu.com.

IRC and Kohai

Nodejitsu has a channel on freenode at
irc://irc.freenode.net/#nodejitsu, where Nodejitsu
developers are standing by to support users around the clock. Drop by to ask
questions, get assistance or even just to hang out!

Kohai is an IRC bot that has some basic abilities
to help you among other features. To bring up his help dialogue just type !help into
the #nodejitsu channel and Kohai will message you.

Github Issues

Each of Nodejitsu's open source projects uses Github Issues to manage bugs and
related software problems. Github Issues is most useful for developers. For
example, if a developer finds a bug in our open-source
http proxy, they can submit an
issue at https://github.com/nodejitsu/node-http-proxy/issues and tell us about
their bug.

Table of Appendices

Appendix: package.json

Understanding the package.json format

A package.json file describes your application, its dependencies, and other various application metadata. For a detailed spec on creating a package.json you can check out Isaac's fine documentation here.

Preparing a package.json for your application

Nodejitsu requires that you create a valid package.json for your application. The package.json will determine certain important pieces of information about your application which are required for deployment. Since sometimes it can get confusing when constructing your package.json file, we provide wizards in our CLI tool and on our website for creating one.

Notice the "scripts" property? This is where you'll store information about specific scripts in your application. The "start" property indicates the script that will get called when your application is started. Usage is compatible with npm start.

Specifying dependencies in your package.json

If your application requires additional dependencies or third-party libraries, Nodejitsu fully supports npm module dependency resolution. All you have to do is list your dependencies the exact same way you would if you were packaging a module for npm. Here is an example of the same package.json with a few dependencies.

Appendix: Building the Nodejitsu Handbook

Dependencies

Make and htmldoc should be available via your operating system's package manager
(ie. apt-get). ronn is available on rubygems, which in
turn should be available via your operating system's package manager as well. On
Debian-based systems, the rubygems package does not add its bin folder
(/var/lib/gems/1.8/bin) to your $PATH variable, so add something
like:

PATH="/var/lib/gems/1.8/bin:$PATH"

to the end of your ~/.profile file and activate it by running . ~/.profile.

Build Process

Once you've installed the dependencies, all you have to do is:

$ make

and the files ./book.md, book.pdf, book.html, API.md and ReadMe.md
should all be generated.