Getting started

Jean-Philippe Encausse edited this page Mar 13, 2018 · 71 revisions

You can try VISEO Bot Maker on Windows with an all-in-one zip release. Simply unzip the archive then click start.bat.The default flow use SARAH nodes running Microsoft Speech Engine locally.

But to go further with Microsoft Bot Framework, Google Home, Alexa or WeChat the machine MUST expose online webhooks.

Create a Virtual Machine

The VISEO Bot Maker has been tested with Ubuntu 14 on Azure, AWS, and Google. See FAQ for Detailed Configuration.

  1. Create an Account. Cloud Services required a Credit Card but offer free small VM.
  2. Create a Virtual Machine matching requirement
  3. Setup Firewall (open port 80, 443 and 1880)
  4. Connect throught SSH (use Putty on Windows)

Install the Server

First you need to install all unix requirement in order to run NodeJS, PM2, NGinx, ...


Use NVM to get a proper NodeJS installation:

wget -qO- | bash
nvm install 8

We recommend using NVM so that node is tied to your user privileges thus preventing any security issues resulting from the use of the root user (or sudo).


We also strongly recommend you install PM2 to manage your NodeJS processes. It will restart your processes if they crash.

npm install -g pm2

Install the VISEO Bot Maker

The VISEO Bot Maker relies on : A set of Node-RED modules (this repo) already deployed on NPM and used by a core project and a bot project

You should have the following files:

-- framework/
---- node_modules/ <== (installed by package.json)
-- bot/            <== (aka your bot)
---- data/         <== (all bot's data)

The VISEO BOT Project

The VISEO BOT Maker relies on Node-RED and supplies a series of modules for bot conversation design. You can install it by typing the following commands:

mkdir ~/mybot && cd ~/mybot
mv node-red-viseo-bot-master framework
cd framework
npm install

Your BOT Project

We provide a template to easily get started with a Chat bot project with our Framework. This folder will contain all the information specific to your bot :

  • conf : configuration files for Node-RED and the framework (  see below )
  • data : all the data for your bot (conversation flows, local databases...etc)
  • node-red-contrib : any additional node-red-contrib module you would want to install in your project
  • webapp : content your app needs to serve, including medias

This template can be installed by using the following command lines

cd ~/mybot
mv viseo-bot-template-master bot

At this point, you might want to follow our recommandations and version  your project.

Configure the VISEO Bot Maker

In our framework, the file framework/conf/node-red-config.js is a copy of Node-RED's settings.js to manage custom configuration. We have modified it so that it would accept environmental variables and also so that it would load additional conf information in the bot/conf/config.js.

Set a Passsword

Among other things, this file defines the credentials that will grant you access to the bot editing interface. You MUST update the password defined in this file.

First create a new password with the command lines:

npm install bcryptjs
node -e "console.log(require('bcryptjs').hashSync(process.argv[1], 8));" your-password-here

Copy the resulting hash. Then edit your config.js file:

cd ~/mybot/bot/conf/
vim config.js

Search for the following lines, change the username and paste the password:

"admin": {
    users: [{
        username: "demo",
        password: "new password hash", 
        permissions: "*"


In this example, the configuration is set for the config.devenvironment. You will need to define similar configurations for each environment you will need.

In the same file, you can also change the value to match your bot url.

Run the Node-RED Server

The template contains 2 scripts using PM2: and start.bat. You MUST call these script FROM bot directory ~/mybot/bot

On Unix or Mac:

cd ~/mybot/bot
../framework/ -p 1880 --env dev --credential-secret MySecret MyFirstBot


cd ~/mybot/bot
bash ../framework/ [ -p port ] [ --url http://url ] [ --docker ] --env [ dev|prod ] [ --credential-secret passphrase ] Appname

The parameters for these scripts are as follows:

  • p is the port on which Node-RED will run (1880 by default)
  • url is the server url if you wish to override the one you defined in conf/config.js
  • docker specifies if you are running the service from a docker container (the script then uses pm2-docker)
  • env is the environment in which the service will run. Note that this value must match the keys in your conf/config.js file
  • credential-secret is the secret passphrase you want to use to encrypt the credentials in your flows.

Check that the app is launched:

pm2 list

If an error occurred, use the command line pm2 log for more information. Otherwise the server should be available at http://ip-address:1880 (Remember to open the 1880 on you VM to access the webpage)

SSL and Reverse Proxy

The SSL protocol is required:

  • to secrure the access to the Node-RED editor
  • to communicate with third party server like MS Bot Framework, Google Home, Alexa, etc ...

A Reverse proxy is required:

  • to generate a (free) SSL Certificate with Let's Encrypt
  • to provide a secure stream over HTTPs and WSs
  • to serve static files

Go to Advanced Settings to setup SSL and NGinx

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.