• Overview
• App Types
• Environments
• Commands
• JVM
• Spring Boot
• JHipster
• Grails
• Dropwizard
• Play
• Tomcat
• TomEE
• Executable Jar
• Node.js
• Node.js
• Go
• ELF64 Binary
• Revel
• Generic
• Linux x64
• Clients
• Command-line
• Maven
• Gradle
• Platforms
• VirtualBox
• Hyper-V
• AWS
• Solutions
• Custom Domains
• TLS (SSL) Certificates
• Databases
• File Storage
• Debugging
• Profiling
• Live Reloading
• Auto-Scaling
• Travis CI
• New Relic
• Learn More
• Articles
• Videos & Slides
• FAQ
• Release Notes

CloudCaptain supports apps written in JavaScript or any other language and packaged as an .tgz file running on Node.js 5.7 or newer.

Get Started

If you haven't already, start by following Node.js & CloudCaptain tutorial that will get you up and running in 5-10 minutes.

Packaging

Applications should be packaged using with all dependencies marked as bundledDependencies. The easiest way to achieve this is to use npm-bundle.

Start by installing npm-bundle:

> npm install -g npm-bundle

Make sure you shrinkwrap your project (this will create a npm-shrinkwrap.json file):

> npm shrinkwrap

Then simply create the tgz in the directory containing your package.json:

> npm-bundle

And finally fuse and run the CloudCaptain image from that same directory:

> boxfuse run

Node.js version

By default CloudCaptain attempts to autodetect the Node.js version from the engines section in package.json.

If no fixed version is specified, CloudCaptain falls back to the latest Node.js version (Current branch).

If you want to switch to an LTS release or simply a different version, you override this by using the -components.nodejs configuration setting:

> boxfuse run my-app-1.0.tgz -components.nodejs=8.2.1

You can use any version available at nodejs.org.

Ports

By CloudCaptain configures your application's http port as well as the PORT environment variable to 80. If your application has been generated by express it should pick this up automatically. Otherwise you need to adjust either your application or the CloudCaptain ports configuration to match.

Databases

Database auto-provisioning

When using the CloudCaptain database auto-provisioning support, CloudCaptain automatically exposes your database's host, port, name, user and password for the current environment as environment variables.

If your app includes the pg or mysql npm module, CloudCaptain will automatically provision the necessary PostgreSQL or MySQL database in each environment.

Using an existing database

To disable database auto-provisioning and use an existing database set db.type to none when creating your app.

MySQL

To connect to your MySQL database you can use the following code:

var mysql = require('mysql');
var connection = mysql.createConnection({
  host     : process.env.BOXFUSE_DATABASE_HOST,
  port     : process.env.BOXFUSE_DATABASE_PORT,
  user     : process.env.BOXFUSE_DATABASE_USER,
  password : process.env.BOXFUSE_DATABASE_PASSWORD,
  database : process.env.BOXFUSE_DATABASE_NAME,
  ssl      : process.env.BOXFUSE_DATABASE_CA_CERT,
  charset  : 'utf8mb4_unicode_ci',
  timezone : 'utc'
});
// Execute query

This also automatically ensures that all connections to RDS MySQL use TLS (SSL).

PostgreSQL

To connect to your PostgreSQL database you can use the following code:

var pg = require('pg');
var fs = require('fs');

var connectionInfo = {
  host     : process.env.BOXFUSE_DATABASE_HOST,
  port     : process.env.BOXFUSE_DATABASE_PORT,
  user     : process.env.BOXFUSE_DATABASE_USER,
  password : process.env.BOXFUSE_DATABASE_PASSWORD,
  database : process.env.BOXFUSE_DATABASE_NAME
};
if (process.env.BOXFUSE_DATABASE_CA_CERT) {
  connectionInfo.ssl = {
    ca: [fs.readFileSync(process.env.BOXFUSE_DATABASE_CA_CERT, 'utf8')]
  };
}

var client = new pg.Client(connectionInfo);
client.connect(function(err) {
  // Execute query
});

This also automatically ensures that all connections to RDS PostgreSQL use TLS (SSL).

TLS (SSL) Certificates / HTTPS

To expose your app via HTTPS make sure you have a custom domain configured for the environment where you want to run it. Also make sure that you have obtained a valid TLS (SSL) certificate and that your app has been created with app.type set to load-balanced and tls.type set to acm (AWS Certificate Manager).

To listen to the HTTPS port you can use the following code:

var https = require('https');
var fs = require('fs');

var server = https.createServer({
    key: fs.readFileSync('/app-config/boxfuse-selfsigned-key.pem'),
    cert: fs.readFileSync('/app-config/boxfuse-selfsigned-cert.pem'),
    requestCert: false,
    rejectUnauthorized: false
}, app);
server.listen(443);

This will ensure that all network traffic between the ELB and your instances will be encrypted as well.

Root Certificates

CloudCaptain uses the same root certificate bundle as the latest version of Firefox. Additionally CloudCaptain also includes the root certificates for Amazon RDS, so you can connect securely to RDS databases out of the box.

Temporary Files

CloudCaptain configures the JVM to use /tmp as the directory to store temporary files and provisions 1 GB of space by default.

To increase this (up to a maximum of 16 TB), simply set the tmp configuration setting to the number of GB of temp space you need. To prevent CloudCaptain from provisioning any temp space set tmp to 0.

Debugging

Remote debugging (including hot-code replace) with your favorite IDE is fully supported. Details and setup instructions on our debugging page.

Live Reloading

In the dev environment, you can reload changes live by running CloudCaptain at the root of your Node.js project with -live:

> npm install
> boxfuse run -live

Also check out our blog post on how to reload Node.js application live on VirtualBox with CloudCaptain.

Time Zone

By default all CloudCaptain instance use the UTC time zone.

We don't recommend changing this as this greatly simplifies time zone issues in machine to machine communication and cleanly relegates all time zones related aspects to a pure presentation layer concern.

If however you still do want to change this, you can override the default time zone of the instance using the TZ environment variable. For example to change the time zone of your instance to America/Los_Angeles you would do so like this:

> boxfuse fuse -envvars.TZ=America/Los_Angeles

Native binaries and libs

Some Node.js applications also depend on native Linux x64 binaries and libs to do their work. CloudCaptain makes it easy to integrate them into your image.

Simply place your binaries under /native/bin inside your tgz and CloudCaptain will automatically add them to the PATH at runtime in your instances.

If those binaries also depend on additional shared libraries beyond the C library, place the .so files of your libraries under /native/lib inside your tgz and CloudCaptain will automatically add them to the LD_LIBRARY_PATH at runtime in your instances.

$ ldd -v my-native-binary

This effectively means the native binaries and libs should be under a native directory inside your application:

 my-nodejs-app
   package.json
   native
   bin
     my-native-binary
     other-linux-x64-binary
   lib
     my-shared-lib.so
     other-shared-lib.so

Linux Kernel Tuning (experts only)

Kernel arguments

To tune the arguments passed Linux kernel from the bootloader, simply pass them using the -linux.args setting when fusing your image.

sysctl.conf

If you need to tune the Linux kernel running in your instance, simply place a sysctl.conf file at the root inside your tgz file. This effectively means it should be in the root directory of your application:

 my-nodejs-app
   package.json
   sysctl.conf

You can then for example tune the maximum number of file descriptors by simply including the following in sysctl.conf:

fs.file-max = 131072

CloudCaptain will then automatically configure the Linux kernel to use these settings.

ELF64 Binaries