Customize Your Deployment

Rasa X version 0.33.0 or higher is only compatible with Rasa Open Source 2.x. If you are on Rasa Open Source 1.x, please check the compatibility matrix for a compatible version.

Server Quick-Install

You can customize the quick-install script using the environment variables listed below. To apply the settings to a new or an existing deployment, simply (re)run the installation command.

E.g. to configure the Rasa X user password, do the following:

export INITIAL_USER_PASSWORD="my-safe-password"

The -E flag applies environment variables from the current user for sudo:

curl -s get-rasa-x.rasa.com | sudo -E bash

Available Settings:

• INITIAL_USER_PASSWORD (generated by default): The password to log into Rasa X.

• ACTION_SERVER_IMAGE (default: an empty placeholder image): The image which runs your custom actions server (if you don’t have one yet, see Building an Action Server Image).

• ACTION_SERVER_TAG (default: ""): The tag of your action server image.

• ADDITIONAL_CHANNEL_CREDENTIALS: Messaging and voice channels which can be used to send messages to Rasa Open Source. Examples:

  • REST:

    export ADDITIONAL_CHANNEL_CREDENTIALS="rest=''
    

  • Facebook:

    export ADDITIONAL_CHANNEL_CREDENTIALS='facebook.verify="rasa-bit",facebook.secret="secret",facebook.page-access-token="token"'
    

• RASA_X_VERSION (default: 0.42.6): Version of Rasa X to install. Don't forget to specify a compatible Rasa Open Source version with the RASA_VERSION variable.

• RASA_VERSION (default: 2.8.14): Version of Rasa Open Source to install.

• DEBUG_MODE (default: false): Runs the deployment in debug mode which provides more information to debug the deployment in case of problems.

• ENABLE_DUCKLING (default: False): Define if the deployment should include Duckling.

Note

The Quick-Install script provides a quick deployment to get started. It provides only essential customization options. If you want to have more control over the deployment, you can use the Rasa X Helm Chart directly.

Helm Chart

Making Changes to the Deployment

If you want to change values for an installed Rasa X deployment, please follow these steps.

1. To modify the parameters of an existing deployment, set the relevant values in your values.yml.

2. Get the release name which Helm used during the installation. If you are unsure which release name was used, use the following command to find out the release name:

   helm list --namespace <your namespace>
   

3. Upgrade the deployment:

   helm repo update
   helm upgrade \
       --values values.yml \
       --namespace <your namespace> \
       --reuse-values \
       <your release name> rasa-x/rasa-x
   

Adding a Custom Action Server

1. To use a custom action server you need to build a Docker image for your action server. Please see Building an Action Server Image for more information on how to build an image and deploy it to a registry.

2. Add the image and tag you want to use to the values.yml. If your image is stored in a private registry, please refer to this guide in order to see how to add image pull secrets to your deployment.

    # app (custom action server) specific settings
    app:
       # name of the custom action server image to use
       name: "<name of your action server image>"
       # tag refers to the custom action server image tag
       tag: "<tag of your image>"
    ```

### Configuring Rasa Open Source Channels

To configure the [messaging and voice channels](/content/docs/rasa/user-guide/messaging-and-voice-channels/index.html) which the Rasa container should use, put the content of your `credentials.yml` in the `values.yml` as done in this example:

```yaml
# rasa: Settings common for all Rasa containers
rasa:
   # additionalChannelCredentials which should be used by Rasa to connect to various input channels
   additionalChannelCredentials:
       socketio:
           user_message_evt: user_uttered
           bot_message_evt: bot_uttered
           session_persistence: true/false

Adding Environment Variables

To add extra environment variables to your containers, add the environment variable to an extraEnvs array on the service in your values.yml. These values can be provided directly or refer to secrets. The extraEnvs parameter is available for the rasa, rasax, eventService, and app services. For example:

# rasa: Settings common for all Rasa containers
rasa:
   # other configured parameters
   # ...
   extraEnvs:
   - name: "SANIC_RESPONSE_TIMEOUT"
     value: 7200
   # app (custom action server) specific settings
   app:
   # other configured parameters
   # ...
   extraEnvs:
   - name: "SECRET_USERNAME"
     valueFrom:
       secretKeyRef:
           name: "login-secret"
           key: "username"

Adding Image Pull Secrets for Private Registries

1. Create a secret for your private registry. You can do so by following the Kubernetes or OpenShift guide.

2. Add the name of the created secret to your values.yml.

   # images: Settings for the images
   images:
      # imagePullSecrets which are required to pull images for private registries
      imagePullSecrets:
         - name: <name of your pull secret>
   

Create / Update Rasa X Users

1. Get the name of the Rasa X pod:

• Kubernetes
  • OpenShift

   kubectl --namespace <your namespace> get pod -l app.kubernetes.io/component=rasa-x
   # The output should be similar to this
   # NAME READY STATUS RESTARTS AGE
   # rasa-rasa-x-6dcf57bb45-jnt4f 1/1 Running 2 17h

rasa-rasa-x-6dcf57bb45-jnt4f is in our case the name of the Rasa X container.

2. Connect to the shell of this pod:
   • Kubernetes
   • OpenShift

   kubectl --namespace <your namespace> exec -it <name of the Rasa X pod> bash

3. Rasa Enterprise only: Run the following command to create a new user. Please see Role-Based Access Control for available default roles.

python scripts/manage_users.py create <username> <password> <role>

4. To update the password of an existing user (the username for the single Rasa X user is me and the role is admin) run the following command:

python scripts/manage_users.py create --update <username> <password> <role>

Debug Mode

Sometimes it’s helpful to have more log messages in the Rasa pods. To activate the debug mode for all Rasa Open Source and Rasa X related pods, use the following configuration in your values.yml:

debugMode: "true"

Specifying Volume Sizes

Rasa X requires two volume claims: one for Rasa X, and one for the database. You can define the claim sizes by setting the size of these services in your override file:

rasax:
   persistence:
      size: "10Gi"
postgresql:
   persistence:
      size: "100Gi"

Using an External Secret

By default, the Helm chart will use the passwords specified in the values.yml and expose them within the cluster as a secret.

You can also provide your own secrets instead of having the Helm chart generate them for you. This section shows you how to create an external secret using the example of the secret which is used for the Rasa components (this does not include components like the database). To see the required structure for secrets used by the subcharts, please follow the documentation of the subcharts. You can find the necessary links in the values.yml of the Rasa X Helm chart.

1. Specify the name of your secret in the values.yml:

rasaSecret: "<name of your secret>"

2. Create a yaml file <secret-filename>.yml which contains the following entries (make sure to replace the <your value> entries):

apiVersion: "v1"
kind: "Secret"
metadata:
   name: "<name of your secret>"
type: "Opaque"
data:
   initialPassword: {{ .Values.rasax.initialUser.password | b64enc | quote }}
   rasaToken: {{ <your value> | b64enc | quote }}
   rasaXToken: {{ <your value> | b64enc | quote }}
   passwordSalt: {{ <your value> | b64enc | quote }}
   jwtSecret: {{ <your value> | b64enc | quote }}

3. Create the secret on the cluster by running this command:
   • Kubernetes
   • OpenShift

   kubectl --namespace <your namespace> apply -f <secret-filename>.yml

4. Then deploy the Rasa X chart. The components will then use the provided external secrets.

Using HTTPS

We recommend that you enable HTTPS on your server by adding SSL certificates (for example using Let’s encrypt).

The recommended way of doing it is to enable SSL on either the ingress controller or the load balancer serving the ingress. Please refer to the documentation of your cloud provider / ingress controller.

You can also configure the Nginx reverse proxy in the chart to use SSL. To do so, you need a PEM-encoded private key file (privkey.pem) and a PEM-encoded certificate chain file (fullchain.pem). Provide their content in a secret, which looks like the following:

apiVersion: "v1"
kind: "Secret"
metadata:
   name: <your secret name>
type: "Opaque"
stringData:
   privkey.pem: <content of the private key file>
   fullchain.pem: <content of the certificate chain file>

Then specify the name of this secret in your override file:

nginx:
   certificateSecret: "<your secret name>"

This will automatically be mounted in the correct place within the Nginx pod.

Configuring the Subcharts

Rasa X builds on existing charts for postgresql, rabbitmq, and redis. To see all configuration values please check the READMEs of the subcharts. The Rasa X chart contains a link to the used chart versions and their READMEs in its values file.

If you don’t want to use the subcharts and decide to provide your own deployments, you can disable the subchart usage through the Rasa X values file. E.g. to skip installing the postgresql subchart specify this in your override file:

postgresql:
   install: false

Additionally, you have to provide the connection details of your external instances and the required credentials. For postgresql this would e.g. be:

postgresql:
   install: false
   existingHost: "<host of your postgres instance>"
   existingSecretKey: "<key to get the password from the secret>"
global:
   postgresql:
       existingSecret: "<name of the secret which contains the database password>"
       servicePort: <port which should be used to connect>
       postgresqlDatabase: "<name of the database which should be used>"
       postgresqlUsername: "<username which should be used to connect>"

Docker Compose

Connecting a Custom Action Server

1. If you don’t yet have an image for your custom action server, follow the instructions in Building an Action Server Image to build your image and push it to a container registry.

2. Replace the default app image with the image of your custom action server:

To avoid your changes in the docker-compose file from being overwritten when you update versions, you should not apply your changes to docker-compose.yml. Instead, create a new file called docker-compose.override.yml inside your /etc/rasa directory 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 contents of docker-compose.override.yml might look like this:

version: '3.4'

services:
   app:
      image: <image:tag>

3. If your Docker containers are already running, take them down and then start Rasa X again:

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

Securing with SSL

You can secure your server with SSL certificates of your choice.

For example, you can use Let’s Encrypt - a free, automated, and open Certificate Authority. It uses an Automatic Certificate Management Environment (ACME) protocol. You can learn more about it on the Getting Started page.

There are many ACME Clients Implementations, for different shell environments and different programming languages.

As an example, we use these ACME clients to generate the SSL certificates:

• Linux
• Windows PowerShell

certbot

Requirements:

• A notification email address (used by Let’s Encrypt to notify about urgent renewal and security notices)
• A 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

All of these instructions should be followed on the server.

• Linux
• Windows PowerShell

Install the ACME client:

Certbot installation instructions for Ubuntu 18.04 LTS

Certbot offers multiple ways to obtain a certificate. Let’s pick the temporary webserver option since it doesn’t require any additional configuration.

If your Rasa-X server is already running, first bring it down:

sudo docker-compose down

Then 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@rasa.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
```bash
sudo cp /etc/letsencrypt/live/rasa.example.com/privkey.pem /etc/rasa/certs/
sudo cp /etc/letsencrypt/live/rasa.example.com/fullchain.pem /etc/rasa/certs/

You can then bring your Rasa X server up again:

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 (you should automate this renewal process with a cron job):

sudo docker-compose down
sudo certbot renew
sudo cp /etc/letsencrypt/live/rasa.example.com/privkey.pem /etc/rasa/certs/
sudo cp /etc/letsencrypt/live/rasa.example.com/fullchain.pem /etc/rasa/certs/
sudo docker-compose up -d

Configuring Databases

Rasa X is officially compatible with the following databases:

• PostgreSQL
• Oracle >= 11.0

By default, Rasa X uses PostgreSQL as a database. It can be configured to use an on-premise database or your own cloud provided database. Using Oracle as your Rasa X database instead of PostgreSQL also requires some additional setup (see below).

PostgreSQL

Please check out the Environment Variables for how to configure Rasa X to use a non-default PostgreSQL database.

Oracle

Using Oracle as your Rasa X database instead of PostgreSQL requires some additional setup, which we’ll go over here.

1. Database Setup

   In your Oracle database, create an empty database called rasa and configure a user/password that has access to it. You can also use a database with a different name, as long as it is empty and you specify this in the DB_DATABASE environment variable (read more in Environment Variables).

2. Rasa X Configuration

   Next you have to extend the Rasa X image to include the necessary drivers and clients. First download the Oracle Instant Client, rename it to oracle.rpm and store it in the directory from where you’ll be building the Docker image.

Copy the following into a file called Dockerfile:

# if using community edition, please replace with rasa-x-ce
FROM gcr.io/rasa-platform/rasa-x-ee:0.42.6
# Switch to root user to install packages
USER root
RUN apt-get update -qq && apt-get install -y --no-install-recommends alien libaio1 && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
# Copy in oracle instaclient
# [https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html](https://www.oracle.com/database/technologies/instant-client/linux-x86-64-downloads.html)
COPY oracle.rpm oracle.rpm
# Install the Python wrapper library for the Oracle drivers
RUN pip install cx-Oracle
# Install Oracle client libraries
RUN alien -i oracle.rpm
USER 1001

You can now use this image instead of the standard one, by replacing it in your docker-compose.override.yml file. You will also have to configure the following environment variables for Rasa X in order to connect to the database:

   DB_USER="<user>" # username used for authentication
   DB_PASSWORD="<password>" # password used for authentication
   DB_DATABASE="rasa" # path to your db
   DB_DRIVER="oracle+cx_oracle"
   DB_PORT="<port of db>" # Port of your SQL server
   DB_HOST="<host of db>" # host of your Oracle server
   DB_QUERY="<query>" # optional dictionary to be added as a query string to the connection URL

:::note To use Oracle for the tracker store, please see the Rasa Open Source docs. :::

Telemetry

Rasa X tracks a minimal amount of anonymized usage information (like how often the “Train” button is used) to help us improve Rasa X. None of your training data or conversations will ever be sent to Rasa. You can disable telemetry by sending the following API request:

curl -X DELETE https://<Rasa X server host>/api/telemetry?api_token=<your api token>

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. These variables have no default value and must be defined in the .env file.

Rasa Variables

These variables define the behavior of the Rasa containers and how the other services connect to them.

Rasa X API Variables

These variables define the behavior of the Rasa X API and how the other services connect to it.

Note

Changing some of these variables requires changes in other containers; for example, if updating your endpoints path, you should also add the new path (relative from the app directory) to the start up command of your Rasa containers with the --endpoints flag.

RabbitMQ Variables

These variables define the behavior of RabbitMQ and how the other services connect to it. More information about RabbitMQ can be found in the RabbitMQ docs.

DB Variables

These variables define the credentials for the PostgreSQL database and configure how other services connect to it.

Redis Variables

These variables define the behavior of the Redis lock store and how other services connect to it.

Duckling Variables

These variables define the behavior of the Duckling service.