notice

This is documentation for Rasa X Documentation v0.37.x, which is no longer actively maintained.
For up-to-date documentation, see the latest version (1.1.x).

Version: 0.37.x

Customize Your Deployment

This page contains information about customizing Rasa X.

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"
# -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.37.4): Version of Rasa X to install. Don't forget to specify the Rasa Open Source version too using the `RASA_VERSION` variable.

  • RASA_VERSION (default: currently latest version): 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 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 which the Rasa container should use, put the content of your credentials.yml in the values.yml as done in this example:

# 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"

To add environment variables to the postgres, rabbit, or redis services, see Configuring the Subcharts.

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 file.

    # 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:
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.

  1. Connect to the shell of this pod:
kubectl --namespace <your namespace> \
exec -it <name of the Rasa X pod> bash
  1. 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>
  2. 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:

kubectl --namespace <your namespace> \
apply -f <secret-filename>.yml
  1. 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 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:

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.

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 them:

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

:::note Be aware that the update process will introduce downtime.

:::

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.37.4
    # 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

    Then build the Docker image:

    docker build . -t rasa/rasa-x:0.37.4-oracle

    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

    Alternatively, you can also directly pass the database connection URL to the container, by defining the DB_URL variable:

    DB_URL="oracle+cx_oracle://user:password@your.database.com:<port>/<database name>"

    :::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>
note

Rasa Enterprise does not track any usage information.

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.

VariableDescription
RASA_X_VERSIONThe version of Rasa X used by the Rasa X docker container.
RASA_VERSIONThe version of Rasa used by the Rasa docker containers.
RASA_TOKENAuthentication token for the Rasa service. This is used by other services to communicate with Rasa.
RASA_X_TOKENAuthentication token for the Rasa X service. This is used by other services to communicate with Rasa X.
PASSWORD_SALTSalt used to securely store the users passwords.
JWT_SECRETSymmetric JWT token for authentication protection of the Rasa API server.
RABBITMQ_PASSWORDUsed by other services to access RabbitMQ.
DB_PASSWORDUsed by other services to access the PostgreSQL database.
REDIS_PASSWORDUsed by other services to access Redis.
RASA_X_DEMO_VERSIONCustom action server version. Only required if using the demo app image.

Rasa Variables

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

VariableDefault ValueDescription
RASA_TOKENNo default, must be defined in .envAuthentication token for the Rasa service. This is used by other services to communicate with Rasa.
RASA_MODEL_PULL_INTERVAL10How often to check for new models, in seconds
RABBITMQ_QUEUE (rasa-production)rasa_production_eventsWhich Rabbit event queue to publish events to.
DB_DATABASE (rasa-production)trackerWhich database table to use to access and store trackers.
DB_DATABASE (rasa-worker)worker_trackerWhich database table to use to access and store trackers.
POSTGRESQL_SCHEMANo defaultPostgreSQL track store database schema to access. By default, Rasa accesses the public schema.
RASA_MODEL_SERVERhttp://rasa-x:5002 /api/projects/default /models/tags/productionURL where to access stored models and store new ones.

Rasa X API Variables

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

VariableDefault ValueDescription
RASA_X_HOST"http://rasa-x:5002"The URL of the Rasa X services. This is used by other services to connect to the Rasa X API.
RASA_X_TOKENNo default, must be defined in .envThe token used for authentication between other services and the Rasa X API.
RASA_X_USERNAME (only for Rasa Enterprise)adminIf RASA_X_PASSWORD is specified then the user with this username will be created automatically after Rasa X is started for the first time.
RASA_X_PASSWORDNo default, must be defined in .env if you want user to be createdIf specified, this user with username RASA_X_USERNAME will be created immediately after Rasa X is started for the first time.
JWT_SECRETNo default, must be defined in .envSymmetric JWT token for authentication protection of the Rasa API server.
RASA_USER_APP""http://app:5055""URL of the custom action server.
RASA_PRODUCTION_HOSThttp://rasa-production:5005Host and port at which to find the rasa-production server.
RASA_WORKER_HOST"http://rasa-worker:5005"Host and port at which to find the rasa-worker server.
RASA_WORKER_TOKENInterpolated from RASA_TOKENAuthentication token used to connect to the Rasa services.
RASA_MODEL_DIR/app/modelsThe directory in which models are stored on the Rasa X container.
RABBITMQ_QUEUErasa_production_eventsWhich queue to read conversation events from.
PASSWORD_SALTNo default, must be defined in .envSalt used to securely store the users passwords.
RASA_X_USER_ANALYTICS0Binary value specifying whether Rasa X UI users’ conversations should be included in conversation analytics in the analytics tab. (Rasa Enterprise only)
SANIC_RESPONSE_TIMEOUT28800Number of seconds a request can run before Sanic generates a 503 response.
SANIC_REQUEST_MAX_SIZE_IN_BYTES800000000Maximum size of requests sent to server. For uploading large models.
SANIC_ACCESS_CONTROL_MAX_AGE1800Value (in seconds) to use for the Access-Control-Max-Age header in responses to preflight requests.
RUN_EVENT_CONSUMER_AS_SEPARATE_SERVICE"false"Whether the event service is run as a separate service. If "false", Rasa X will launch the event service automatically as a subprocess.
JWT_PUBLIC_KEY_PATH"/app/public_key"Path where to store JWT authentication.
JWT_PRIVATE_KEY_PATH"/app/private_key"Path where to store JWT authentication.
JWT_EXPIRATION_TIME28800Expiration time in seconds for JWT tokens.
DEBUG_MODE"false"Whether or not to turn on debug logs.
LOG_LEVEL"INFO"Log level to use, overwritten by DEBUG_MODE if DEBUG_MODE variable is set.
SAML_PATH"/app/auth/saml"Path at which to store SAML authentication (Rasa Enterprise).
SAML_DEFAULT_ROLE"tester"Role to assign to SSO users upon first sign on (Rasa Enterprise).
RASA_MODEL_DIR"/app/models"Directory where models are stored on the Rasa X container.
CREDENTIALS_PATH"/app/credentials.yml"Path to credentials.yml in the Rasa X container.
RASA_X_SSL_CERTIFICATENonePath to SSL certificate if running the rasa-x container on HTTPS.
RASA_X_SSL_KEYFILENonePath to SSL keyfile if running the rasa-x container on HTTPS.
RASA_X_SSL_PASSWORDNonePath to SSL password if running the rasa-x container on HTTPS with a password-protected keyfile.
DEFAULT_E2E_TESTS_DIR"tests"Directory where tests are saved on the Rasa X container.
DEFAULT_E2E_TEST_FILE_PATH"conversation_tests.md"File inside DEFAULT_E2E_TESTS_DIR where end-to-end tests are saved by default on the Rasa X container.
MAX_DUMPING_DELAY_IN_SECONDS60Training data changes are dumped to disk in a batches. This variable describes the maximum time in seconds after which changes are dumped to disk.
POSTGRESQL_SCHEMANo defaultPostgreSQL database schema to access. By default, Rasa X accesses the public schema.
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.

VariableDefault ValueDescription
RABBITMQ_HOST"rabbit"Hostname of the container hosting RabbitMQ.
RABBITMQ_USERNAME"user"Username used by other services to access RabbitMQ.
RABBITMQ_PASSWORDNo default, must be defined in .envPassword used by other services to access RabbitMQ.
RABBITMQ_DISK_FREE_LIMIT"{mem_relative, 0.1}"Disk free space limit of the partition on which RabbitMQ is storing data

DB Variables

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

VariableDefault ValueDescription
DB_HOST"db"Hostname of the container hosting the PostgreSQL database.
DB_PORT"5432"Port used by other services to access the database.
POSTGRESQL_USERNAME (DB_USER)"admin"Username used by other services to access the database.
POSTGRESQL_PASSWORD (DB_PASSWORD)No default, must be defined in .envPassword used by other services to access the database.
DB_LOGIN_DB"rasa"Database connection used to create tracker database.
POSTGRESQL_DATABASE (DB_DATABASE)"rasa"Database used by other services to access the database.

Redis Variables

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

VariableDefault ValueDescription
REDIS_HOST"redis"Hostname of the container hosting Redis.
REDIS_PORT"6379"Port used by other services to access Redis.
REDIS_PASSWORDNo default, must be defined in .envPassword used by other services to access Redis.
REDIS_DB"1"Database name used by other services to access Redis.

Duckling Variables

These variables define the behavior of the Duckling service.

VariableDefault ValueDescription
RASA_DUCKLING_HTTP_URL"http://duckling:8000"Used by other services to access Duckling.