Deploy to a Server

For running Rasa X on a server, we support Docker. We provide template docker-compose files which you can use directly, or you can use them as a basis to run on Kubernetes or OpenShift.

The Docker images for Rasa X Community Edition are freely available via Docker Hub. The images for Rasa X Enterprise Edition are hosted on a private registry and are accessible with an enterprise license.

Running Rasa X using Docker launches several services:

service name	description
rasa-x	Rasa X HTTP API
rasa-production	Rasa service running a trained model, mainly used for parsing intent messages and predicting actions
rasa-worker	Duplicate of rasa-production used for background tasks such as training and evaluating models
db	PostgreSQL database service
duckling	Duckling service used for entity extraction
rabbit	Message broker used to transmit conversation events between rasa-production and rasa-x

Quick Installation

We provide a script for a fully-automated install which works on Ubuntu 16+:

1. If you have an enterprise license, copy it to your server. Skip this step if you are using Rasa X Community Edition.

   $ scp rasa-x-ee-license.yml example.com:~/rasa-x-ee-license.yml
   

2. Download and run the install script on the server:

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

   Replace stable with a 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.

3. Replace the default app image with the image of your custom action server. See this guide for more information on how to do so. To avoid your changes in the docker-compose file being overwritten with the next update, you should not apply your changes to docker-compose.yml. Instead, create a new file called docker-compose.override.yml and apply your changes there. Docker will automatically take that file into account and override any attributes in docker-compose.yml with changes from the override file. The content of docker-compose.override.yml might look like this:

   version: '3.4'
   services:
     app:
       image: <your image>
   

4. Start Rasa X:

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

5. If you are using Rasa X CE, please set your admin password:

   $ cd /etc/rasa
   $ sudo python rasa_x_commands.py create --update admin me PASSWORD
   

   Rasa Enterprise users should instead create an admin user with a username and a password:

   $ cd /etc/rasa
   $ sudo python rasa_x_commands.py create admin USER PASSWORD
   

Navigate to the hostname or IP where your server is reachable and log in using your newly created password.

Hardware & OS Requirements

We recommend 8 GB RAM and 2-6 vCPUs for optimal performance. 4 GB 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 above:

• 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 X 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.

Manual Installation

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

   $ docker -v && docker-compose -v
   

2. Create the project directory and switch to it:

   $ mkdir /etc/rasa
   $ cd /etc/rasa
   

3. Download the Rasa X files (docker-compose.ce.yml and rasa_x_commands.py) that contain the containers and their setup (replacing latest with the version to install). If you want to install the enterprise version, please use docker-compose.ee.yml:

   $ wget -qO docker-compose.yml https://storage.googleapis.com/rasa-x-releases/stable/docker-compose.ce.yml
   $ wget -qO rasa_x_commands.py https://storage.googleapis.com/rasa-x-releases/stable/rasa_x_commands.py
   

4. If you are using Rasa X EE, please create the authentication file to download containers from the private Docker registry. To authenticate against the registry that contains the Rasa X containers, you need to create a file in /etc/rasa/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/rasa/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"
   }
   

   Then log in to the docker registry:

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

5. Create the docker environment file in /etc/rasa/.env with the following content:

   RASA_X_VERSION=stable
   RASA_TOKEN=<random_string>
   RASA_X_TOKEN=<random_string>
   PASSWORD_SALT=<random_string>
   JWT_SECRET=<random_string>
   RABBITMQ_PASSWORD=<random_string>
   

   For <random_string> please use secure strings, e.g. randomly generated character sequences. A convenient way of generating random strings is using openssl:

   $ openssl rand -base64 16
   

   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 Token. This is used to authorize the communication between containers.

   Note

   Make sure to generate a unique <random_string> each time! To do this, re-run the random sequence generator for each field:

   $ openssl rand -base64 16
   

6. Create a credentials file at /etc/rasa/credentials.yml containing:

   rasa:
      url: ${RASA_X_HOST}/api
   

   You can also add credentials for other messaging and voice channels .

   If you want to know more about the used environment variable, see Environment Variables.

7. Add an endpoints file at /etc/rasa/endpoints.yml containing:

   models:
      url: ${RASA_MODEL_SERVER}
      token: ${RASA_X_TOKEN}
      wait_time_between_pulls: ${RASA_MODEL_PULL_INTERVAL}
   tracker_store:
      type: sql
      dialect: "postgresql"
      url: ${DB_HOST}
      port: ${DB_PORT}
      username: ${DB_USER}
      password: ${DB_PASSWORD}
      db: ${DB_DATABASE}
      login_db: ${DB_LOGIN_DB}
   event_broker:
      type: "pika"
      url: ${RABBITMQ_HOST}
      username: ${RABBITMQ_USERNAME}
      password: ${RABBITMQ_PASSWORD}
      queue: ${RABBITMQ_QUEUE}
   action_endpoint:
      url: ${RASA_USER_APP}/webhook
      token:  ""
   

   If you want to know more about the used environment variables, see Environment Variables.

8. Create an environments file at /etc/rasa/environments.yml containing:

   rasa:
      production:
         url: http://rasa-production:5005
         token: ${RASA_TOKEN}
      worker:
         url: http://rasa-worker:5005
         token: ${RASA_TOKEN}
   

   If you are using Rasa X EE you can also add further environments as described in Deployment Environments. If you want to know more about the used environment variables, see Environment Variables.

9. We recommend that you enable HTTPS on your server by adding SSL certificates (for example using Let’s encrypt). Put the generated fullchain.pem and privkey.pem file in the directory /etc/rasa/certs.

10. The Rasa containers are following Docker’s best practices and are not running as root user. Hence, please make sure that the root group has read and write access to the following directories and their content:

    • /etc/rasa/credentials
    • /etc/rasa/endpoints.yml
    • /etc/rasa/environments.yml
    • /etc/rasa/auth
    • /etc/rasa/models
    • /etc/rasa/logs
    • /etc/rasa/terms
    • /etc/rasa/certs

    To set the permissions and group you can use this command:

    sudo chgrp -R root <path> && sudo chmod -R 770 <path>
    

    If you are using different volume mounts please adapt their permissions accordingly.

11. Set the permissions and owner of the database persistence directory /etc/rasa/db using this command:

    sudo chown -R 1001 /etc/rasa/db && sudo chmod -R 750 /etc/rasa/db
    

12. Replace the default app image with the image of your custom action server. See this guide for more information on how to do so. To avoid your changes in the docker-compose file being overwritten with the next update, you should not apply your changes to docker-compose.yml. Instead, create a new file called docker-compose.override.yml and apply your changes there. Docker will automatically take that file into account and override any attributes in docker-compose.yml with changes from the override file. The content of docker-compose.override.yml might look like this:

    version: '3.4'
    services:
      app:
        image: <your image>
    

13. Start up Rasa X (-d will run Rasa X in the background):

    $ sudo docker-compose up -d
    

14. If you are using Rasa X CE, please set your admin password:

    $ cd /etc/rasa
    $ sudo python rasa_x_commands.py create --update admin me PASSWORD
    

    Rasa Enterprise users should instead create an admin user with a username and a password:

    $ cd /etc/rasa
    $ sudo python rasa_x_commands.py create admin USER PASSWORD
    

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
RASA_X_DEMO_VERSION	Custom Action Server version.
CORE_SDK_VERSION	The SDK version used by the Custom Action Server.
RASA_VERSION	The version of Rasa used by the Rasa docker containers.
RASA_TOKEN	Authentication token for the Rasa service. This is used by other services to communicate with Rasa.
RASA_MODEL_DIR	Directory in which Rasa models are stored.
JWT_SECRET	JWT token for authentication between services and the Rasa X API.

The Rasa 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:

• rasa-x
• rasa-production

Variable	Explanation
RASA_MODEL_PULL_INTERVAL	Pull interval for Rasa, in seconds.
RASA_MODEL_SERVER	URL of the model server (API).
RASA_USER_APP	URL of the custom action server.
RASA_WORKER_HOST	host of the Rasa worker service
RASA_DUCKLING_HTTP_URL	URL of Duckling, used for entity extraction.

The Rasa X API variables group

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

• rasa-x
• rasa-production

Variable	Explanation
PASSWORD_SALT	Salt used to securely store the users passwords.
RASA_X_USER_ANALYTICS	Flag used to show/hide the analytics tab.
RASA_X_HOST	The URL of the Rasa X services. This is used by other services to connect to the Rasa X API.
RASA_X_TOKEN	The token used for authentication between other services and the Rasa X API.
SANIC_RESPONSE_TIMEOUT	General timeout for request (seconds).
SELF_PORT	Port used by the Rasa X service.

The RabbitMQ variables group

These variables define the behaviour of the RabbitMQ and how the other services connect to it. More information about RabbitMQ can be found here. This group of variables is used by the following services:

• rasa-x
• rasa-production
• 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.

Installing Updates

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

$ curl https://example.com/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-x-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/rasa
$ # If you are using Rasa X EE, log in to the private Docker registry
$ sudo docker login  -u _json_key -p "$(cat /etc/rasa/gcr-auth.json)" https://gcr.io
$ # Pull the new images
$ sudo docker-compose pull

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

$ cat .env

Start the updated version of Rasa X:

$ sudo docker-compose up -d

Once Rasa X is up and running, you can log in using your user credentials and test it.

Warning

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

• /etc/rasa/docker-compose.yml
• /etc/rasa/.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.