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:

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:

    Copy

    export ADDITIONAL_CHANNEL_CREDENTIALS="rest=''"

  • Facebook:

    Copy

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

• RASA_X_VERSION (default: 0.41.2): 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.7.1): 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.

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:

   Copy

   helm list --namespace <your namespace>

3. Upgrade the deployment

   Copy

   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.

   Copy

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

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:

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.

   Copy

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

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

2. Connect to the shell of this pod:

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

   Copy

   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:

   Copy

   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:

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:

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:

   Copy

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

   Copy

   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:

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:

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

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:

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

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:

   Copy

   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:

   Copy

   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.

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:

   Copy

   # if using community edition, please replace with rasa-x-ce

   FROM gcr.io/rasa-platform/rasa-x-ee:0.41.2

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

   Copy

   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:

   Copy

   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:

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.

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.