# Rasa X Installation Guide ## Compatibility 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](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/changelog/compatibility-matrix) for a compatible version. ## License Terms For the use of Rasa X the [Rasa X License Terms](https://storage.googleapis.com/rasa-x-releases/rasa_x_ce_license_agreement.pdf) apply. For the use of Rasa Enterprise the [Rasa Enterprise License Terms](https://storage.googleapis.com/rasa-x-releases/rasa_x_ee_license_agreement.pdf) apply. This page contains detailed instructions for installing Rasa X in a scalable cluster environment using OpenShift or Kubernetes (K8S). Rasa X is available as a [Helm Chart](https://helm.sh/) for a cluster setup. If you are not using Helm in your cluster, you can still use the following instructions to generate the Kubernetes or OpenShift object configurations via the Helm command-line interface and install those configurations manually. ### Note The Rasa X Helm chart is open-source and available in the [rasa-x-helm repository](https://github.com/rasahq/rasa-x-helm). Please [create an issue](https://github.com/RasaHQ/rasa-x-helm/issues/new) in this repository if you discover bugs or have suggestions for improvements. ## Requirements **Note: Rasa X is intended to be installed on a server and not to a personal/local machine. Installing on a server is recommended because Rasa X is designed to stay up continuously, and not to be frequently stopped or restarted.** ### Cluster Requirements To install the Rasa X Helm chart, you need an existing [Kubernetes cluster](https://kubernetes.io/) or [OpenShift cluster](https://www.openshift.com/). Setting up a Kubernetes / OpenShift cluster can be tedious, hence we recommend getting a managed cluster from a cloud provider like [Google Cloud](https://cloud.google.com/kubernetes-engine), [DigitalOcean](https://www.digitalocean.com/products/kubernetes/), [Microsoft Azure](https://azure.microsoft.com/en-us/services/kubernetes-service/), or [Amazon EKS](https://aws.amazon.com/eks/). The requirements of the single pods can vary, especially those of the `rasa-production` and `rasa-worker` pods, dependent on the model size and what pipeline is used and the number of users. We recommend providing at least the following resources: | Deployment | CPU | Memory | |-------------------|-----|---------| | rasa-x | 1 | 1 GiB | | event-service | 2 | 1 GiB | | rasa-production | 2 | 2 GiB | | rasa-worker | 4 | 4 GiB | | nginx | 0.2 | 200 MiB | | app | 0.5 | 200 MiB | | duckling | 0.5 | 200 MiB | | postgresql | 1 | 250 MiB | | rabbit | 0.2 | 250 MiB | | redis | 0.2 | 250 MiB | We recommend a size of 10 GiB for the Rasa X volume claim and at least 30 GiB for the database volume claim. ### Installation Requirements 1. Please check that you installed the Kubernetes or OpenShift command line interface (CLI). You can check this using the following command: ```bash kubectl version --short --client ``` The output should be similar to: ``` Client Version: v1.16.3 ``` If this command resulted in an error, please install the [Kubernetes CLI](https://kubernetes.io/docs/tasks/tools/install-kubectl/) or the [OpenShift CLI](https://docs.openshift.com/container-platform/4.3/cli_reference/openshift_cli/getting-started-cli.html#cli-installing-cli_cli-developer-commands) depending on the cluster you’re using. 2. Make sure that the Kubernetes / OpenShift CLI is correctly connected to your cluster. You can do so by using the following commands: ```bash kubectl version --short ``` The output should be similar to: ``` Client Version: v1.16.3 Server Version: v1.14.8-gke.12 ``` If you get an error when executing the command, you are not connected to your cluster. To get the command to connect to the cluster please consult your cluster’s admin or the documentation of your cloud provider. 3. Please make sure you have the [Helm CLI](https://helm.sh/docs/intro/install/) installed. To check this, run: ```bash helm version --short ``` The output should be similar to: ``` v3.0.0+ge29ce2a ``` If this command leads to an error, please install the [Helm CLI](https://helm.sh/docs/intro/install/). 4. In case you are using a version `<3` of Helm, please update to Helm version `3`. ### Supported Browsers The web interface aims to support [browsers that meet the following criteria](https://browserl.ist/?q=%3E0.2%25%2Cnot+ie+%3C%3D+11%2Cnot+op_mini+all): - > 0.2% market share - not Internet Explorer - not Opera Mini ### Subchart Versions The [Rasa X Helm charts](https://github.com/RasaHQ/rasa-x-helm) by default make use of three Bitnami subcharts, which pull the images in the table below. | Subchart | Chart Version | Image | Image Version | |-------------|---------------|------------------------------------|---------------| | [redis](https://github.com/bitnami/charts/tree/master/bitnami/redis) | 10.5.14 | [bitnami/redis](https://hub.docker.com/r/bitnami/redis) | 5.0.8 | | [rabbit](https://github.com/bitnami/charts/tree/master/bitnami/rabbitmq) | 6.19.2 | [bitnami/rabbitmq](https://hub.docker.com/r/bitnami/rabbitmq) | 3.8.3 | | [postgresql](https://github.com/bitnami/charts/tree/master/bitnami/postgresql) | 8.6.13 | [bitnami/postgresql](https://hub.docker.com/r/bitnami/postgresql) | 11.7.0 | If you choose to override the subchart defaults, or use external instances of them, you should verify in the relevant changelogs whether the versions you are using take different values than the ones listed below or on the Helm chart repo. ## Installation ### 1. Create Namespace We recommend installing Rasa X in a separate [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) to avoid interfering with existing cluster deployments. To create a new namespace run the following command: ```bash kubectl create namespace ``` ### 2. Create Values File Prepare an empty file called `values.yml` which will include all your custom configuration for the installation with Helm. ### 3. Configure Credentials To configure the credentials, copy the section below into the `values.yml` file and replace each `` marker with a different alphanumeric string. Please use safe credentials to avoid data breaches. ```yaml # rasax specific settings rasax: initialUser: password: "" # password for the Rasa X user passwordSalt: "" # passwordSalt Rasa X uses to salt the user passwords token: "" # token Rasa X accepts as authentication token from other Rasa services jwtSecret: "" # rasa: Settings common for all Rasa containers rasa: token: "" # RabbitMQ specific settings rabbitmq: rabbitmq: password: "" # global settings of the used subcharts global: postgresql: postgresqlPassword: "" redis: password: "" ``` ### 4. Specify Rasa X and Rasa Open Source Versions You can install the latest stable Rasa X version and the latest Rasa Open Source version by specifying the following in your `values.yml`: ```yaml # rasax specific settings rasax: tag: "0.42.6" # rasa: Settings common for all Rasa containers rasa: tag: "2.8.14-full" ``` To install the latest edge release of Rasa X instead, set the `latest` tag for Rasa X: ```yaml rasax: tag: "latest" rasa: tag: "2.8.14-full" ``` You can also choose any compatible Rasa X and Rasa Open source versions according to the [Compatibility Matrix](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/0.42.x/changelog/compatibility-matrix). ### 5. Configure Rasa X Image There’s nothing you need to do for this section. ### 6. Optional: Configure Custom Action Server See [these instructions](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/0.42.x/installation-and-setup/customize#adding-a-custom-action-server) to configure a custom action server. ### 7. Deploy Rasa X Run the following commands: ```bash # Add the repository which contains the Rasa X Helm chart helm repo add rasa-x https://rasahq.github.io/rasa-x-helm # Deploy Rasa X helm install \ --generate-name \ --namespace \ --values values.yml \ rasa-x/rasa-x ``` **OpenShift only**: If the deployment fails and `oc get events` returns `1001 is not an allowed group spec.containers[0].securityContext.securityContext.runAsUser`, re-run the installation command with an added `--set securityContext.fsGroup=null` flag. Then wait until the deployment is ready. If you want to check on its status, the following command will block until the Rasa X deployment is ready: ```bash kubectl --namespace \ wait \ --for=condition=available \ --timeout=20m \ --selector app.kubernetes.io/component=rasa-x \ deployment ``` Alternatively you can also [monitor the pods directly](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/0.42.x/installation-and-setup/install/helm-chart/#accessing-logs). Note that the deployment process can involve containers restarting until everything is ready (e.g. if the database container is not ready yet). ### 8. Access Rasa X By default the Rasa X deployment is exposed via the `nginx` service. You can get the IP address using this command: ```bash kubectl --namespace \ get service \ -l app.kubernetes.io/component=nginx \ -o jsonpath="{.items..status..loadBalancer..ingress[0].ip}" ``` You can then access the deployment on `http://:8000` **Note:** Depending on the used cluster / cloud provider this might not work. Please refer to the cloud provider’s documentation / administrator for the recommended way for exposing the `nginx` service. ## Reference ### Accessing Secrets This section describes how to retrieve secrets from your running deployment. You have the option to retrieve the following secrets: | description | default secret name | |---------------------------------------------|----------------------| | PostgreSQL database password | `postgresql` | | Redis lock store and cache password | `redis` | | RabbitMQ event broker password | `rabbit` | Run the following command, replacing `` with one of the values in the table, and `` and `` with your namespace and the name of your release: ```bash secret= namespace= release_name= kubectl --namespace ${namespace} \ get secret ${release_name}-${secret} -o yaml | \ awk -F ': ' '/password/{print $2}' | base64 -d ``` ### Accessing Logs This section describes how to get logs from the running containers. 1. Get the name of the [pod](https://kubernetes.io/docs/concepts/workloads/pods/pod/) which you want to get the logs of. ```bash kubectl --namespace \ get pods ``` To get the logs of the container run: ```bash kubectl --namespace \ logs ``` ### Using Helm to Generate Object Configurations If you don’t want or cannot use Helm to install Rasa X in your cluster, you can still use Helm to generate the Kubernetes / OpenShift resource files. 1. Follow the [installation instructions](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/0.42.x/installation-and-setup/install/helm-chart/#installation) until the deployment part. 2. Run the following command to generate the Kubernetes / OpenShift resource files and write them in a file `rasa-x-deployment.yml`: ```bash helm repo add rasa-x https://rasahq.github.io/rasa-x-helm helm repo update helm template \ --namespace \ --values values.yml \ \ rasa-x/rasa-x > rasa-x-deployment.yml ``` 3. You can then deploy these manually by running: ```bash kubectl --namespace \ create -f rasa-x-deployment.yml ``` ## Next Steps - [Connect a Custom Action Server](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/0.42.x/installation-and-setup/customize#adding-a-custom-action-server) if you are using custom actions. - [Set up Integrated Version Control](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/0.42.x/installation-and-setup/deploy#integrated-version-control) to connect your Rasa X instance to a remote Git repository. - [Deploy your assistant](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/0.42.x/installation-and-setup/deploy#how-to-deploy) using Rasa X. - [Configure SSL](https://legacy-docs-rasa-x.rasa.com/docs/rasa-x/0.42.x/installation-and-setup/customize#using-https) if you’d like to run your Rasa X server on HTTPS.