notice

This is documentation for Rasa X/Enterprise Documentation v1.0.x, which is no longer actively maintained.
For up-to-date documentation, see the latest version (1.4.x).

Version: 1.0.x

Customize Your Deployment

This page contains information about customizing Rasa X.

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
warning

It's possible to deploy Rasa Open Source using the Rasa X Helm chart, but this option is deprecated and will be removed in the future.

See the Rasa Helm chart to learn how to configure Rasa Open Source Channels for deployment that was deployed via the Rasa Helm chart.

note

These settings only work if you deployed Rasa Open Source via the Rasa X Helm chart. It is recommended to use the Rasa Helm chart to deploy Rasa Open Source. Please see the Rasa Open Source deployment docs for details.

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>

The secret has to be created before you deploy Rasa X. If you use rasactl to create a deployment, you can define a namespace with the secret as an argument in CLI, e.g. the secret has been created in the my-namespace namespace, then use the rasactl start my-namespace command to create Rasa X deployment.

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 (by default, the username for the single Rasa X user is admin and its role is admin) run the following command:

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

If you created a deployment via rasactl, the namespace name is the same as a deployment name. You can use the rasactl list command to display available deployments.

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

If you use rasactl to create a deployment, you can define a namespace with the secret as an argument in CLI, e.g. the secret has been created in the my-namespace namespace, then use the rasactl start my-namespace command to create Rasa X deployment.

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.

Deploying to a Subpath

By default, Rasa X assumes it is being served at the root of the host. To serve it at a subpath, e.g. "/rasa-x", you will need to:

1) set the environmental variable ROOT_URL in the rasa-x pod to the full URL you want Rasa X to be served at e.g.:

rasa-x:
extraEnvs:
- name: "ROOT_URL"
value: www.example.com/rasa-x

2) configure Nginx/your ingress (depending on which you're using) to use the correct subpath. For Nginx, you will need to create a customized version of rasax.nginx.template that includes the subpath everywhere in the server definition. See the instructions for configuring Nginx.

Configuring Nginx

If you are using Nginx and you need to customize it's configuration to e.g. serve Rasa X at a subpath or enable SSL, you will need to create a custom config map.

Your configmap should include at least the keys nginx.conf, ssl.conf, and rasax.nginx.template. If you include additional keys for other configuration templates, you need to specify the paths to which to mount these files under nginx.extraVolumeMounts. The standard versions of nginx.conf, ssl.conf, and rasax.nginx.template can be found here. Assuming your customized versions of these files are in the directory ./custom-nginx-conf-files, you can create a custom configmap as follows:

kubectl -n your-namespace create configmap custom-nginx-conf --from-file ./custom-nginx-conf-files

To use your custom configmap, specify its name in your values:

nginx:
# custom config map containing nginx.conf, ssl.conf.template, rasax.nginx.template
customConfConfigMap: "custom-nginx-conf"

The configmap has to be created before you deploy Rasa X. If you use rasactl to create a deployment, you can define a namespace with the secret as an argument in CLI, e.g. the secret has been created in the my-namespace namespace, then use the rasactl start my-namespace command to create Rasa X deployment.

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

Deploying to a Subpath

By default, Rasa X assumes it is being served at the root of the host. To serve it at a subpath, e.g. "/rasa-x", you will need to

Use the following configuration in your values.yaml to define a Subpath.

nginx:
subPath: "/rasa-x"
rasa-x:
extraEnvs:
- name: "ROOT_URL"
value: www.example.com/rasa-x

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:

    FROM rasa/rasa-x:1.0.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:1.0.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

Activating Rasa Enterprise will automatically disable telemetry.

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/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.
ROOT_URL"/"Root URL for the frontend to check for resources. Use this if you are hosting your Rasa X instance on a subdirectory of a domain. No trailing slash.
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.