Deploying Node.js apps

Clever Cloud allows you to deploy any Node.js application. This page will explain you how to set up your application to run it on our service.

You do not need to change a lot in your application, the requirements will help you to configure your apps with some mandatory files to add, and properties to setup.

Create an application

Refer to the page Deploy an application on Clever Cloud.


Be sure that:

  • you have pushed in master branch
  • you listen on
  • your package.json either has a scripts.start or main field

The following code describes a Hello world application listening on port 8080:

// Load the http module to create an http server.
const http = require('http');

// Configure our HTTP server to respond with Hello World to all requests.
const server = http.createServer((request, response) => {
  response.writeHead(200, {"Content-Type": "text/plain"});
  response.end("Hello World\n");

// Last, but not least, listen on port 8080
// The environment variable PORT is automatically defined and equals to 8080
server.listen(process.env.PORT, '');

Then, a package.json file is mandatory to initiate your app deployment on Clever Cloud. The next section will detail this point.

Describing package.json

Even if you have no dependencies, you have to provide a package.json file at the root of your project’s directory.

About dependencies:
  • For every Node.js project you HAVE TO provide a package.json file at the root of your project’s directory.
  • Additionally, make sure that the folder "/node_modules" is in your .gitignore file before pushing your app.

If you already are a Node.js guru, you probably won't have to change anything to that file. Just check the required fields below.

The package.json file should look like the following:

  "name" : "myapp",
  "version" : "0.1.0",
  "main" : "myapp.js",
  "scripts" : {
    "start" : "node myapp.js"
  "engines" : {
    "node" : "^10"

The json fields

The following table describes each of the fields formerly mentioned.

Usage Field Description
At least one scripts.start This field provides a command line to run. If defined, npm start will be launched. Otherwise we will use the main field. See below to know how and when to use the scripts.start field
main This field allows you to specify the file you want to run. It should be the relative path of the file starting at the project's root. It's used to launch your application if scripts.start is not defined.
Optional engines.node Sets the node engine version you app runs with. Any "A.B.x" or "^A.B.C" or "~A.B" version will lead to run the application with the latest "A.B" local version. If this field is missing, we use the latest LTS available. If you want to ensure that your app will always run, please put something of the form "^A.B.C" and avoid setting only ">=A.B.C".

Build and start

When deploying an application, there are two phases: build and run.

  • The build phase installs the dependencies and executes the scripts.install in your package.json (if defined). It's meant to build the whole application including dependencies and / or assets (if there are any).

  • The run phase is executed from scripts.start if defined. This phase is only meant to start your application and should not contain any build task.

All the build part should be written into the scripts.install field of the package.json. You can also add a custom bash script and execute it with: "scripts.install": "./"

For more information, see the npm documentation

NPM modules dependencies

If you need some modules you can easily add some with the dependencies field.

Here is an example :

  "name" : "myapp",
  "version" : "0.1.0",
  "main" : "myapp.js",
  "scripts" : {
    "start" : "node myapp.js"
  "engines": {
    "node": "^10"
  "dependencies": {
    "express": "3.x",
    "": "0.9.x",
    "underscore": "1.4.3"

As of now, we will always install development dependencies even if NODE_ENV=production is set, using either npm install --production=false or yarn install --production=false. An environment variable might be added in the future to let you control this behaviour. Please reach out to our support if you need such environment variable.

Deploy with privates dependencies

If your application got privates dependencies, you can add a Private SSH Key.

Node.js supported versions

Clever Cloud can virtually run any version of node >= 0.6 and any module. Lesser (pre-npm) versions are not officially supported. Unstable versions are not supported either. You can use the engines.node field in package.json to define the wanted version.

Supported package managers

We support npm and yarn as package managers.

The environment variable NODE_BUILD_TOOL allows you to define which build tool you want to use. It can be one of these values:

If the variable isn't defined or if another value is provided, it will default to npm.

Environment injection

Clever Cloud can inject environment variables that are defined in the dashboard and by add-ons linked to your application.

To access your variable in your application, nothing simpler! Just get it from your environment: process.env.MY_VARIABLE.

You can (and should) define the NODE_ENV=production environment variable as many frameworks rely on it for production mode.

Special env NPM_TOKEN

Since April 2015, allows you to have private repositories. The bad news is, you have to write a specific line in your .npmrc for that. The good news is, on Clever Cloud, you only need to provide the token part, and we set up everything for you!

So to register your npm auth token, you need to add to your application the NPM_TOKEN environment variable.


As you can see, only the authToken value is needed, not the full url you can find in your .npmrc.

Custom run command

If you need to run a custom command (or just pass options to the program), you can specify it through the CC_RUN_COMMAND environment variable.

For instance, for a meteor application, you can put

CC_RUN_COMMAND=node .build/bundle/main.js <options>

Troubleshooting your application

If you are often experiencing auto restart of your nodeJS instance, maybe you have an application crashing that we automatically restart. To target this behaviour, you can gracefully shutdown with events handlers on uncaughtExeption unhandledRejection sigint and sigterm and log at this moment so you can fix the problem.

Automatic HTTPS redirection

If you are using Express.js, you can use express-sslify by adding:

app.use(enforce.HTTPS({ trustProtoHeader: true }))

Otherwise, you can read the X-Forwarded-Proto header.

Deploy on Clever Cloud

Application deployment on Clever Cloud is via Git. Follow these steps to deploy your application.

Deployment video

More info on

Edit me on GitHub