Installation

Platform Installation Instructions

This document is for developers / sysadmins who want to install Rasa Platform on premise or on a private cloud.

Note

Rasa uses docker compose to manage the lifecycle of the containers. The installation script should be used to provision a new server. If you want to run the application alongside other software on an existing server, you should consider installing docker compose manually.

Quickstart

1. copy the license file to the server. To get a license file, you need to buy a Rasa Platform subscription. If you don’t have one yet, please contact us.

$ scp rasa_platform.yml example.com:~/rasa_platform.yml
  1. Download and run the install script on the server:
$ curl -sSL -o install.sh https://storage.googleapis.com/rasa-releases/stable/install.sh
$ sudo bash ./install.sh

Replace stable with a specific version number if you want to install a specific version. You will be prompted to accept the terms and conditions. Type YES and hit return.

  1. Start the Platform
$ cd /etc/rasaplatform
$ sudo docker-compose up -d
  1. Create a Platform user you can use to log in
$ cd /etc/rasaplatform
$ sudo python rasa_commands.py create admin USER PASSWORD

replacing the USER and PASSWORD fields, for example python rasa_commands.py create admin admin PasswOrd.

Navigate to the hostname or IP where your server is reachable and log in via the interface. Once you are logged in you can start Setting Up Your Bot.

Detailed Setup

Rasa Platform is built as a collection of docker containers. Here we provide suggested hardware for running on a single server.

Hardware & OS Requirements

We recommend 8Gb RAM & 2-6 vCPUs for optimal performance. 4Gb RAM is the bare minimum. Your server should also have 100 Gb Disk space available. You will need a server running a modern Linux distribution that can run docker. The following OS’s work with the easy install script below:

  • Debian 7.7+
  • Ubuntu 14.04 / 15.10 / 16.04

For any other operating systems, please follow the manual installation instructions. As long as docker is available for your operating system, Rasa Platform should run fine.

The web interface aims to support browsers that meet the following criteria

  • > 0.2% market share
  • Not Internet Explorer
  • Not Opera Mini

Firewall

Make sure the following ports are open:

Port Service Description
443 HTTPS Web application over HTTPS access.
80 HTTP Web application access.
22 SSH SSH access.

If you install on Google Cloud this means:

  • make sure to check “Allow HTTP traffic” as well as “Allow HTTPS traffic” in the firewall settings of the VM instance.

Prepare the installation

Before you can install Rasa Platform, you need to have a license file. We will send you that file, it is named rasa_platform.yml. It contains licensing information as well as configuration parameters.

Make sure to upload the license file to the server, e.g. using

$ scp rasa_platform.yml HOSTNAME:~/rasa_platform.yml

where HOSTNAME is the hostname or ip of your server.

Install Docker Compose

Rasa uses docker compose to spin up a collection of docker containers that combined make up the Platform. You can either install a specific release, or use latest which corresponds to the most recent release (we recommend pinning a specific version though).

Download the install script and run it. Make sure the current directory contains the license file:

$ curl -sSL -o install.sh https://storage.googleapis.com/rasa-releases/stable/install.sh
$ sudo bash ./install.sh

The installation script will install docker compose and ansible. ansible is a popular tool for automation - it will download the docker compose setup as well as prepare the environment for docker to run in.

The Platform-related files will be installed into /etc/rasaplatform. This includes credentials to login to the docker registry under /etc/rasaplatform/gcr_auth.json.

Note

Although, this is the easiest way to get your server ready to run the Platform you can also follow the manual steps which will walk you through a few extra steps but will give you more control over the setup.

Accept the terms and conditions

To accept the terms and conditions, run echo "${USER} $(date)" > /etc/rasaplatform/terms/agree.txt. You can find the terms here.

Start the application

After you have successfully installed the Platform you can now start it:

$ cd /etc/rasaplatform
$ sudo docker-compose up -d

This will run the Platform in the background (due to -d) and the application will continue to run even if you log out of the server.

Create a User

To log in to the Platform, you need to create user accounts. At first, it is best to create at least one administrator account. To do so run:

$ cd /etc/rasaplatform
$ sudo python rasa_commands.py create admin USER PASSWORD

replacing the USER and PASSWORD fields, for example python rasa_commands.py create admin admin PasswOrd.

To create non-admin users, just replace admin with user:

$ sudo python rasa_commands.py create user USER PASSWORD

Note

The admin role has access to all API endpoints. The user role can only send messages and view their own conversation with the bot. For more information on account roles, head over to the docs on Platform Account Roles.

Test Your Login

Visit http://HOSTNAME in a web browser, and log in with the username & password entered in the previous command.

Installing Updates

To see which version you are currently running, hit the /version endpoint:

$ curl hostname/api/version

To install an update, fetch the install.sh for your version, and run it:

$ curl -sSL -o install.sh https://storage.googleapis.com/rasa-releases/VERSION/install.sh
$ sudo bash ./install.sh

replacing VERSION with the version you want to install.

After the installation is complete, login to the docker registry and pull the image:

$ cd /etc/rasaplatform
$ sudo docker login  -u _json_key -p "$(cat /etc/rasaplatform/gcr-auth.json)" https://gcr.io
$ sudo docker-compose pull

Make sure that the docker environment file is updated by running:

$ cat .env

Start the updated version of the platform:

$ sudo docker-compose up -d

Once the platform is up and running, you can login using your user credentials and test it.

Warning

Be aware, that during the update the following files will be overwritten:

  • /etc/rasaplatform/docker-compose.yml
  • /etc/rasaplatform/.env

Make sure there are no changes in these files that you still need. E.g. instead of directly modifying docker-compose.yml you should rather create a new file called docker-compose.override.yml. Docker will automatically take that file into account and override any attributes in docker-compose.yml with changes from the override file.

Next Steps

Now that you have the main pieces of the Platform installed, you can go ahead and Setting Up Your Bot.

Manual Installation

  1. Make sure python, docker, and docker compose are installed on your Platform. Detailed instructions can be found in the docker documentation. You should be able to run

    $ docker-compose --version
    
  2. Create the project directory and switch to it:

    $ mkdir /etc/rasaplatform
    $ cd /etc/rasaplatform
    
  3. Download the Platform files (docker-compose.yml and rasa_commands.py) that contain the containers and their setup (replacing latest with the version to install):

    $ wget -qO docker-compose.yml https://storage.googleapis.com/rasa-releases/stable/docker-compose.yml
    $ wget -qO rasa_commands.py https://storage.googleapis.com/rasa-releases/stable/rasa_commands.py
    
  4. Create the authentication file to download containers from the docker registry. To authenticated with the registry that contains the Platform containers, you need to create a file in /etc/rasaplatform/gcr-auth.json that contains the JSON of the field docker_registry_license from your license.

    Make sure to copy everything between the outer " of the docker_registry_license key to that file. The contents of /etc/rasaplatform/gcr-auth.json should look like this:

    {
      "type": "service_account",
      "project_id": "rasa-platform",
      "private_key_id": "sdferw234qadst423qafdgxhw",
      "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvfwrt423qwadsfghtzw0BAQEFAASCBKgwggSkAgEAAoIBAQCgt338FkWbW13dghtzew4easdf5wAi15jrA9t4uOk8dghrtze4weasfgdhtAFZNfrLgvr2\nPBTu1lAJDLo136ZGTdMKi+/TuRqrIMg/sr8q0Ungish8v6t5Jb4gsjBi9StytCT4\nhWXDL3qeadfsgeDOudl6c3iMzylBws+VffrFfaZWjDpGtxmlYwIUa2e\noNSe7BYLnY9tDrX3zrP/wu/6FPbbGkBjguDG1l3Kx7l1wmiPtK5lIhjt+k7Oyx/u\nd6+gvfs+7RX9wUxnZT/tLggybYdsr8BA1Pqr0hDmhdDl7tjXVTmGLG+1/+lXVGFc\nqKEg+uLXAgMBAAECggEAESzwRK0Cp62LgBjInk+jvTmMI4lYP/XTnfk0TNwyiLxd\nT7mkw/TzkSVRifZ37lBQ6BS6BiqBJherh1N4xI+DF9HUN/wHR93QTyu7p8umlcxC\nlPV0KE4b5ZMfWvRG4y236cRGly9urcBNGoFzFHl8pd2iS5DMqZOYpSXY+qvkXTKE\nUOm5mVSs4S4Qa9cHL+jWXCvY0789fG1GrT+L3Fn+StKacgQuBnN1krYFYBSjCAh8\nsnSdjkvGguw/6OApPHd8HqkHtjU0PD67uU5QIm5N1bmz9KT4s9Pm+WbCinEstIiN\nIfln5ikmHcMAiIS0gzSnZavsY21PsDHBkD8SUO7CTQKBgQDgMPhx0TsB/oVH/SnU\nt3oTME+tfAKI69tozX02jHj6DY/vDpI1hXNmb4oMOos5+3ulborHqnso9za1RgV7\nm2N04QQVfzYEuZzJzXL11SHvBYVjHkXYy6HR5GhnPmwA+CzrDNy2/oYxlaqH7TBA\nR+f7IHToIPKGCVrhCJztlAgzIwKBgQC3hQNclIQ5Iw0gm9Rr8zAP/YoRJdiUSYtv\nNBmav+dTTSkPh51Bomj/J4Rrg8OLvHG5U79pmzbQdIFGYGKlR0l4/QepKpbaGm7x\nM/gRp/GXu9sN8LgI+h+FskCYi4cuqDjQ9L2S0gwMre4witmeVSIiBxLWxS7mvkZX\nWRW58ml2vQKBgBozPuW2SQobn6HhIUFdy+NwMu+YXYd44ORnl2mHkx/N8/NBJa8h\nkHH5OQ3izaCSFkooGAnrj4cjFP6sVzmx2DaxkVOd0UdOFdezreqy5MtVPthtkkYa\nzieEZPsj3WVjm4RAtY6hQjeLQSmve4MXpDHCAkeaih1F/Jvt8MEHGso3AoGBAJez\nTioTYpFQliNkbN2nMw2kyaKPJE6/1JDiAmBXTcMgP1blBWsh86UnZ2DwlI5IAcHu\npoWHlnIOPGaOejyhhuyKTPDbkcNMonSkPuVpbF2/Hb6SQ664A6KizJ7Mh7xbtkuU\nY7igBPHePMzHmkg1m3eBXWNHsBNxKfg+XaVN6zwJAoGBAN6VhGMmyDcn0GqkkP6d\nrSsQ0Ig7L4PnU633oYWoGWa8q/XYiFbcACMFynMbrmHG+/0c3Iwt32bi3th60Cwb\nT66yqmv4MaT72+EfQHxiLxnUxhqSpBXM0eoXbyvDg97Zp/slsYvGGLjONmmretlE\nsjAsuAH4Iz1XdfdenzGnyBZH\n-----END PRIVATE KEY-----\n",
      "client_email": "company@rasa-platform.iam.gserviceaccount.com",
      "client_id": "114123456713428149",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "token_uri": "https://accounts.google.com/o/oauth2/token",
      "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
      "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/company%40rasa-platform.iam.gserviceaccount.com"
    }
    
  5. Login to the docker registry

    $ sudo docker login  -u _json_key -p "$(cat /etc/rasaplatform/gcr-auth.json)" https://gcr.io
    
  6. Create the docker environment file in /etc/rasaplatform/.env with the following content:

    RASA_PLATFORM_VERSION=stable
    RASA_NLU_TOKEN=<random_string>
    RASA_CORE_TOKEN=<random_string>
    RASA_PLATFORM_TOKEN=<random_string>
    PASSWORD_SALT=<random_string>
    MONGO_PASSWORD=<random_string>
    JWT_SECRET=<random_string>
    RABBITMQ_PASSWORD=<random_string>
    

    For <random_string> please use secure strings, e.g. randomly generated character sequences.

    For the token and password salt fields, enter any string of your choice. These will be used to hash passwords. Note that if you change these you will have to create new logins for everyone.

    You will also need to set a Rasa NLU and Rasa Core Token. These are needed to ensure only you have access.

    Note

    Make sure to generate a different unique <random_string> for each field! E.g. running this multiple times:

    $ openssl rand -base64 12
    
  7. Create a credentials file at /etc/rasaplatform/credentials.yml containing:

    rasa:
       url: http://api:5002
    
  8. Start up the Platform (-d will run the Platform in the background):

    $ sudo docker-compose up -d
    

Environment Variables

Global environment variables

This group of variables is mainly used by docker-compose. All the variables get interpolated when starting the services with docker-compose up and then are passed to services. It is possible to see the docker-compose.yml file with the substituted variables by using docker-compose config.

Variable Explanation
PLATFORM_UI_VERSION The compatible UI version for the Platform.
PLATFORM_DEMO_VERSION Custom Action Server version.
CORE_VERSION The version of Rasa Core used by the Platform.
CORE_SDK_VERSION The SDK version used by the Custom Action Server.
NLU_VERSION The version of Rasa NLU used by the Platform.
SPACY_VERSION The version of Spacy used by Rasa NLU.
SPACY_ENGLISH_MODEL_BASE English language model used by Spacy.
SPACY_ENGLISH_MODEL_VERSION Version of the English language model used by Spacy.
SPACY_GERMAN_MODEL_BASE German language model used by Spacy.
SPACY_GERMAN_MODEL_VERSION Version of the German language model used by Spacy.
TENSORFLOW_VERSION The version of Tensorflow used.
RASA_NLU_TOKEN=nlutoken Authentication token for the NLU service. This is used by other services to communicate with NLU.
RASA_CORE_TOKEN Authentication token for the Core service. This is used by other services to communicate with Core.
JWT_SECRET JWT token for authentication between services and the API.

The Core variables group

These variables define the behaviour of Rasa Core and how the other services connect to it. This group of variables is used by the following services:

  • api
  • core
Variable Explanation
RASA_CORE_HOST URL of the Core service.
RASA_CORE_MODEL_DIR The directory in which Core models are stored.
RASA_CORE_MODEL_PULL_INTERVAL Pull interval for Core, in seconds.
RASA_CORE_MODEL_SERVER URL of the model server (API).
RASA_NLG_ENDPOINT_URL Natural Language Generation endpoint.
RASA_REMOTE_CORE_ENDPOINT_URL Must be the same as RASA_CORE_HOST.
RASA_USER_APP URL of the custom action server.
RASA_CORE_WORKER_TOKEN Set equal to RASA_CORE_TOKEN.

The MongoDB variables group

These variables define the behaviour of MongoDB and how the other services connect to it. For more information please visit https://github.com/bitnami/bitnami-docker-mongodb. This group of variables is used by the following services:

  • api
  • core
  • event-service
Variable Explanation
MONGO_INITDB_ROOT_USERNAME This variable is used to create the root user during the startup of MongoDB.
MONGO_INITDB_ROOT_PASSWORD This variable is used to create the root password during the startup of MongoDB.
MONGO_DB The name of the database used by the services.
MONGO_HOST URL of the MongoDB database. It should use the mongodb protocol.
MONGO_PASSWORD This variable is used by other services to access MongoDB. It should be equal to MONGO_INITDB_ROOT_PASSWORD.
MONGO_USERNAME This variable is used by other services to access MongoDB. It should be equal to MONGO_INITDB_ROOT_USERNAME.

The NLU variables group

These variables define the behaviour of NLU and how the other services connect to it. This group of variables is used by the following services:

  • api
  • core
  • nlu
Variable Explanation
RASA_DUCKLING_HTTP_URL URL of Duckling, used for entity extraction.
RASA_NLU_HOST URL of Rasa NLU. This is used by other services to connect to Rasa NLU.
RASA_NLU_MODEL_DIR The path where the NLU models are stored.
RASA_NLU_MODEL_SERVER The URL used by other services to request NLU models.
RASA_NLU_WORKER_TOKEN Set equal to RASA_NLU_TOKEN

The Platform API variables group

These variables define the behaviour of the Platform API and how the other services connect to it. This group of variables is used by the following services:

  • api
  • core
  • nlu
Variable Explanation
PASSWORD_SALT Salt used to securely store the users passwords.
PLATFORM_USER_ANALYTICS Flag used to show/hide the analytics tab.
RASA_PLATFORM_HOST The URL of the API services. This is used by other services to connect to the API.
RASA_PLATFORM_TOKEN The token used for authentication between other services and the API.
SANIC_RESPONSE_TIMEOUT General timeout for request (seconds).
SELF_PORT Port used by the API service.

The RabbitMQ variables group

These variables define the behaviour of the RabbitMQ and how the other services connect to it. For more information please visit https://github.com/bitnami/bitnami-docker-rabbitmq#configuration. This group of variables is used by the following services:

  • api
  • core
  • event-service
Variable Explanation
RABBITMQ_DEFAULT_PASS This variable is used to create the password for the default user during startup.
RABBITMQ_DEFAULT_USER This variable is used to create the username for the default user during startup.
RABBITMQ_HOST Hostname of the container hosting RabbitMQ.
RABBITMQ_PASSWORD This is used by other services to access RabbitMQ. Must be equal to RABBITMQ_DEFAULT_PASS.
RABBITMQ_USERNAME This is used by other services to access RabbitMQ. Must be equal to RABBITMQ_DEFAULT_USER.

The UI file

This file is used by the following services:

  • platform-ui
Variable Explanation
REACT_APP_API_URL The URL used by the application as the base for API calls.

SSL Certificates

Setting up a Let’s Encrypt SSL Certificate

Rasa Platform works very well together with a Let’s Encrypt SSL Certificate.

Requirements:

  • notification email address (used by Let’s Encrypt to notify about urgent renewal and security notices)
  • domain name for the installation (in this example we use rasa.example.com) - you will not be able to set up SSL with a bare IP address without DNS

Note

Changing the systems DNS entries will create downtime.

We will use certbot to generate the certificates. Run these instructions to install the tool on a Ubuntu machine (needs to be adapted for other linux distros):

  1. SSH into the machine
  2. run the following commands to install certbot:
$ sudo apt-get update
$ sudo apt-get install software-properties-common
$ sudo add-apt-repository ppa:certbot/certbot
$ sudo apt-get update
$ sudo apt-get install certbot

certbot offers multiple ways to obtain a certificate. Let’s pick the temporary webserver option since it doesn’t require any additional configuration. The only prerequisite though is that the Rasa Platform has to be stopped so that webserver can bind to port 443 properly. To stop the Platform, run:

$ sudo docker-compose down

Now, run the following to start the interactive process to obtain the SSL certificate:

$ sudo certbot certonly

It’ll first ask you to pick the authentication method:

How would you like to authenticate with the ACME CA?
-------------------------------------------------------------------------------
1: Spin up a temporary webserver (standalone)
2: Place files in webroot directory (webroot)
-------------------------------------------------------------------------------
Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 1

Here, pick 1 and press return.

Then, fill in the aforementioned email address:

Enter email address (used for urgent renewal and security notices) (Enter 'c' to
cancel): ops@example.com

Then, accept the Terms of Services and decide if you’d like to share your email address with the EFF:

-------------------------------------------------------------------------------
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf. You must agree
in order to register with the ACME server at
https://acme-v01.api.letsencrypt.org/directory
-------------------------------------------------------------------------------
(A)gree/(C)ancel: A

-------------------------------------------------------------------------------
Would you be willing to share your email address with the Electronic Frontier
Foundation, a founding partner of the Let's Encrypt project and the non-profit
organization that develops Certbot? We'd like to send you email about EFF and
our work to encrypt the web, protect its users and defend digital rights.
-------------------------------------------------------------------------------
(Y)es/(N)o: N

In the last step you’re providing your domain name:

Please enter in your domain name(s) (comma and/or space separated)  (Enter 'c'
to cancel): rasa.example.com

After that finished successfully, you’ll see a message similar to the one below:

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
   /etc/letsencrypt/live/rasa.example.com/fullchain.pem
   Your key file has been saved at:
   /etc/letsencrypt/live/rasa.example.com/privkey.pem
   Your cert will expire on 2018-02-07. To obtain a new or tweaked
   version of this certificate in the future, simply run certbot
   again. To non-interactively renew *all* of your certificates, run
   "certbot renew"

Your certificate has been generated and is now saved on the machine at /etc/letsencrypt/live/rasa.example.com/. Please run the following to copy them over to the appropriate directory so that the docker container can access them:

$ sudo cp /etc/letsencrypt/live/rasa.example.com/privkey.pem /etc/rasaplatform/certs/
$ sudo cp /etc/letsencrypt/live/rasa.example.com/fullchain.pem /etc/rasaplatform/certs/

After you have copied these files you can restart the Rasa Platform:

$ sudo docker-compose up -d

Let’s Encrypt certificates are short-lived, this means they expire after 90 days. This means that you’ll have to renew them on a regular basis. Thankfully this can be done with certbot as well. Run the following commands in order to renew your certificate.

Note

Be aware that the update process will also introduce downtime.

$ sudo docker-compose down
$ sudo certbot renew
$ sudo docker-compose up -d

In general: These certificate renewals should be automated with a cron job.