Here’s what you’ll have after completing this guide:

  • a website running Node.js
  • a starting point to continue with the Node guides

This guide will help get you started. We'll take you through key steps, introduce you to important concept and point you to further documentation and other resources along the way. It's not intended to be a complete tutorial, and you will need to be prepared to look further into some topics on your own if necessary. 

A plain-text code editor to work on the code and configuration is required. Atom, Sublime and Visual Studio are all excellent choices.

About Node.js

Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine, providing an asynchronous event-driven framework for scalable network applications.

Before we begin

Before we create a project, please familiarise yourself with the basics of Divio Cloud. Some key topics and resources:

Some of these guides will make more sense and be most useful once you have already dived in and are working with Divio Cloud.

Create a new project

Create a new project with the following configuration:

  • Platform: Node
  • Type: Node
  • Boilerplate: Default

Then select a suitable subscription and create the project.

By default, Divio Cloud installs the latest Long Term Release (LTS) version of Node.

Set up the project locally

You will need to be aware of some key topics as we continue - refer to these articles if necessary as you go along:

Once you have installed and launched the Divio App on your computer, set up the the project you just created by clicking Setup:

This will take a few minutes to conclude. Once completed hit Start to launch your local server.

Now you can open your local website using the "eye" icon on the top right of the Local Server in the Divio App or open up in a browser. Once you have logged in, you should see the a page with the message "Hello world!".

Not working? Retrace your steps, and pay close attention to any error messages, as they will contain important information about the problem. You will also find valuable guidance in the material recommended above.


About Docker

Divio Cloud uses Docker to run your projects locally. This allows you to use any programming language – be it Python, Node or PHP – locally, without configuring your operating system to support it. If you are experience issues, have a look at our troubleshooting section or our Docker guide.

Preparing for the Node tutorial

Before you can start the Node guides, we need to do a few more things:

Code editor

Open the source folder in a code editor. You'll find it by selecting the "folder" icon in the Divio App and opening the whole directory in your editor:

Using a shell

You will need to run commands in a command line environment. The Divio App makes this easy for you - just click on the Divio Shell button on the lower left of the app. This will create a terminal shell with all the necessary environment variables in place.

Everything should show up with green checks - if not trace your steps back to resolve it.


About shell commands

You should be familiar with basic shell commands such as cd , open and cp as they are essential items in the developer's toolbox. The Learn Python the Hard Way tutorial has a very good appendix introducing these commands.

Entering commands

The tutorial will ask you to run specific commands such as:

  • npm install <package>   

You will need to run these inside the Docker container of your project, not in your own environment on your computer. To get into the container, run the following command in the Divio Shell:

  • docker-compose run --rm web bash 

Don't forget to cd to into the project folder first.

You can also issue commands in the shell to run in the container, by prefixing them with docker-compose run --rm web . For example:

  • docker-compose run --rm web npm install <package>

Divio Command Line Interface

It's very helpful to understand the basic commands for the Divio CLI (Command Line Interface). For example, you can use it to start and stop the server inside the shell far quicker then the Divio App. Some helpful commands:

  • divio project up   to start the local development server
  • divio project stop  to stop a project
  • divio project update  to update the local development server

Basic Docker commands

Docker also provides a number of helpful commands. See our documentation for more, but for now you should know about:

  • docker-compose up  - starts the server (stop it with control-c)

Managing files

You can upload and download files from your local server to the test server easily using the Divio App. Simply use the corresponding Download and Upload controls and select what you want to transfer from the menu.

The underlying technology behind the file management is Git. If you type git status into an open shell inside the project you will get a report, perhaps something like:

The Divio App automatically commits these changes into your Git repository. Divio provides a Git server as part of the service.


About Git

Git is a version control system (VCS) and tracks the history of your changes as people and teams collaborate together on a project. It is very helpful to be familiar with Git and what it does. An excellent starting point is the very popular Git tutorial on GitHub.

Start the Node tutorial

Now head over to the Node guides and start your journey as a Node developer. 

We have provided a basic example in the index.js file, feel free to modify it and play around.

Some remarks

  1. You might encounter a slightly different file structure from the Node guides. This is fine - many developers have their own preferred style. Our setup uses an opinionated structure. We describe the differences in more detail in our developers section.
  2. It is sometimes required to restart the server after a change; you can do this through the Divio App by clicking on Stop/Start. If the server still doesn't run try docker-compose logs  to see what the issue is. It may be a simple typo or missing modules import.


Divio Cloud provides a Postgres database for each project. You can connect to this by installing the "pg" package via npm install pg --save . An example configuration to work locally would look like this:

const pg = require('pg');
const config = {
    user: 'postgres',
    database: 'db',
    password: '',
    host: 'db',
    port: 5432
const pool = new pg.Pool(config);

You need to get the database connection information from the DEFAULT_DATABASE_DSN  environment variable which outputs :


As the database settings are different form the local, test and live environments. An alternative integration can be found on the express-boilerplate using pg-promise.

Sometimes it takes some time for the database to be available locally. For this add the following to your docker-compose.yml web service section:

command: bash -c 'while !</dev/tcp/db/5432; do sleep 1; done; npm start'
  - db

For further documentation please consult the "Pooling example" found in node-postgres and our express-boilerplate alternative.

Media Storage

Divio Cloud leverages S3 to store media files on the test or live servers. When developing locally, files are stored on your computer rather than S3.

To configure and access your S3 storage service simply use the  DEFAULT_STORAGE_DSN environment variable.

You can find further information about how to interact with your project’s media storage in our support section.

Did this answer your question?