From dca63a4117bfde9ad1f65cbc5dd96b4c944fbe30 Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 24 Feb 2020 11:27:18 +0100 Subject: [PATCH 01/27] info heirarchy docker docs --- docs/user-guide/how-to-deploy.rst | 57 +++++++++++++++++-------------- 1 file changed, 31 insertions(+), 26 deletions(-) diff --git a/docs/user-guide/how-to-deploy.rst b/docs/user-guide/how-to-deploy.rst index 6b846998ef81..5e394f36921f 100644 --- a/docs/user-guide/how-to-deploy.rst +++ b/docs/user-guide/how-to-deploy.rst @@ -2,7 +2,7 @@ .. _deploying-your-rasa-assistant: -Deploying your Rasa Assistant +Deploying Your Rasa Assistant ============================= .. edit-link:: @@ -15,7 +15,7 @@ It will allow you to make your assistant available to users and set you up with :depth: 2 -When to deploy your assistant +When to Deploy Your Assistant ----------------------------- .. raw:: html @@ -55,6 +55,7 @@ It is also possible to deploy a Rasa assistant using Docker Compose without Rasa .. contents:: :local: + :depth: 2 Installing Docker @@ -76,18 +77,17 @@ See `Docker Installation `_ for details. Building an Assistant with Rasa and Docker ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This section will cover the following: +If you don't have a Rasa project yet, you can build one in Docker without having to install Rasa Open Source +on your local machine. If you already have a model you're satisfied with, skip ahead to :ref:`running-the-rasa-server` +to deploy your model. - - Setting up your Rasa project and training an initial model - - Talking to your AI assistant via Docker - - Choosing a Docker image tag - - Training your Rasa models using Docker - - Talking to your assistant using Docker - - Running a Rasa server with Docker +.. contents:: + :local: + :depth: 2 -Setup -***** +Setting up your Rasa Project +**************************** Just like in the :ref:`tutorial `, you'll use the ``rasa init`` command to create a project. The only difference is that you'll be running Rasa inside a Docker container, using @@ -123,11 +123,11 @@ The initial project files should all be there, as well as a ``models`` directory .. note:: - By default Docker runs containers as ``root`` user. Hence, all files created by - these containers will be owned by ``root``. See the `documentation of docker + By default Docker runs containers as user ``1001``. Hence, all files created by + these containers will be owned by this user. See the `documentation of docker `_ and `docker-compose `_ if you want to - run the containers with a different user. + run the containers as a different user. Talking to Your Assistant ************************* @@ -147,10 +147,10 @@ you need to pass the ``-it`` flags. Customizing your Model -~~~~~~~~~~~~~~~~~~~~~~ +********************** Choosing a Tag -************** +############## To keep images as small as possible, we publish different tags of the ``rasa/rasa`` image with different dependencies installed. See :ref:`choosing-a-pipeline` for more information @@ -178,7 +178,7 @@ Alternatively, you can use the ``-full`` tag, which includes all pipeline depend .. _model_training_docker: Training a Custom Rasa Model with Docker -**************************************** +######################################## Edit the ``config.yml`` file to use the pipeline you want, and place your NLU and Core data into the ``data/`` directory. @@ -214,6 +214,7 @@ You can also leave these out since we are passing the default values. that your module is in the Python module search path by setting the environment variable ``PYTHONPATH=$PYTHONPATH:``. +.. _running-the-rasa-server: Running the Rasa Server ~~~~~~~~~~~~~~~~~~~~~~~ @@ -253,6 +254,10 @@ recommend to use `Docker Compose `_. Docker Compose provides an easy way to run multiple containers together without having to run multiple commands. +.. contents:: + :local: + :depth: 2 + Start by creating a file called ``docker-compose.yml``: .. code-block:: bash @@ -300,14 +305,14 @@ To run the services configured in your ``docker-compose.yml`` execute: Adding Custom Actions -~~~~~~~~~~~~~~~~~~~~~ +********************* To create more sophisticated assistants, you will want to use :ref:`custom-actions`. Continuing the example from above, you might want to add an action which tells the user a joke to cheer them up. Creating a Custom Action -************************ +######################## Start by creating the custom actions in a directory ``actions``: @@ -344,7 +349,7 @@ Continuing with the example bot from ``rasa init``, replace ``utter_cheer_up`` i ``action_joke`` to the actions in the domain file. Adding the Action Server -************************ +######################## The custom actions are run by the action server. To spin it up together with the Rasa instance, add a service @@ -383,7 +388,7 @@ Run ``docker-compose up`` to start the action server together with Rasa. Adding Custom Dependencies -************************** +########################## If your custom action has additional dependencies of systems or Python libraries, you can add these by extending the official image. @@ -411,7 +416,7 @@ You can then build the image via the following command, and use it in your docker build . -t : Adding a Custom Tracker Store -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +***************************** By default, all conversations are saved in memory. This means that all conversations are lost as soon as you restart the Rasa server. @@ -419,7 +424,7 @@ If you want to persist your conversations, you can use a different :ref:`Tracker Store `. Using PostgreSQL as Tracker Store -********************************* +################################# Start by adding PostgreSQL to your docker-compose file: @@ -440,7 +445,7 @@ configuration ``config/endpoints.yml``: db: rasa Using MongoDB as Tracker Store -****************************** +############################## Start by adding MongoDB to your docker-compose file. The following example adds the MongoDB as well as a UI (you can skip this), which will be available @@ -476,7 +481,7 @@ configuration ``endpoints.yml``: Then start all components with ``docker-compose up``. Using Redis as Tracker Store -**************************** +############################## Start by adding Redis to your docker-compose file: @@ -495,7 +500,7 @@ configuration ``endpoints.yml``: url: redis Using a Custom Tracker Store Implementation -******************************************* +########################################### If you have a custom implementation of a tracker store you have two options to add this store to Rasa: From 2fec14d01520f5d1bbf6bed74549d1241c83fffd Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 24 Feb 2020 14:26:26 +0100 Subject: [PATCH 02/27] update docker action server docs --- docs/user-guide/how-to-deploy.rst | 116 ++++++++++++++++++++++-------- 1 file changed, 85 insertions(+), 31 deletions(-) diff --git a/docs/user-guide/how-to-deploy.rst b/docs/user-guide/how-to-deploy.rst index 5e394f36921f..6e78999fd04b 100644 --- a/docs/user-guide/how-to-deploy.rst +++ b/docs/user-guide/how-to-deploy.rst @@ -311,8 +311,8 @@ To create more sophisticated assistants, you will want to use :ref:`custom-actio Continuing the example from above, you might want to add an action which tells the user a joke to cheer them up. -Creating a Custom Action -######################## +Running a Custom Action in Docker-Compose +######################################### Start by creating the custom actions in a directory ``actions``: @@ -348,12 +348,16 @@ Continuing with the example bot from ``rasa init``, replace ``utter_cheer_up`` i ``data/stories.md`` with the custom action ``action_joke``, and add ``action_joke`` to the actions in the domain file. -Adding the Action Server -######################## +To instruct Rasa to use the action server you have to tell Rasa its location. +Add this to your ``endpoints.yml`` (if it does not exist, create it): + +.. code-block:: yaml -The custom actions are run by the action server. -To spin it up together with the Rasa instance, add a service -``action_server`` to the ``docker-compose.yml``: + action_endpoint: + url: http://app:5055/webhook + +To spin up the action server together with the Rasa instance, add a service +``app`` to the ``docker-compose.yml``: .. code-block:: yaml :emphasize-lines: 11-14 @@ -368,7 +372,7 @@ To spin it up together with the Rasa instance, add a service - ./:/app command: - run - action_server: + app: image: rasa/rasa-sdk:latest volumes: - ./actions:/app/actions @@ -376,44 +380,94 @@ To spin it up together with the Rasa instance, add a service This pulls the image for the Rasa SDK which includes the action server, mounts your custom actions into it, and starts the server. -To instruct Rasa to use the action server you have to tell Rasa its location. -Add this to your ``endpoints.yml`` (if it does not exist, create it): +Run ``docker-compose up`` to start the action server together with Rasa. -.. code-block:: yaml +.. warning:: - action_endpoint: - url: http://action_server:5055/webhook + If you create a more complicated + action that has extra library dependencies, you will need to + :ref:`build an action server image` to run your code. -Run ``docker-compose up`` to start the action server together -with Rasa. +.. _building-an-action-server-image: -Adding Custom Dependencies -########################## +Deploying an Action Server Image +################################ -If your custom action has additional dependencies of systems or Python libraries, -you can add these by extending the official image. +If you build an image that includes your action code and store it in a container registry, you can run it locally +or as part of your Rasa X or Rasa Enterprise deployment, without having to move code between servers. +In addition, you can add any additional dependencies of systems or Python libraries +that are part of your action code but not included in the base ``rasa/rasa-sdk`` image. -To do so, create a file named ``Dockerfile`` in which you extend the official -image and add your custom dependencies. For example: +This documentation assumes you are pushing your images to `DockerHub `_. +DockerHub will let you host multiple public repositories and +one private repository for free. Be sure to first `create an account `_ +and `create a repository `_ to store your images. You could also push images to +a different Docker registry, such as `Google Container Registry `_, +`Amazon Elastic Container Registry `_, or +`Azure Container Registry `_. + +To create your image, first create a list of your custom actions requirements in a file, +``actions/requirements-actions.txt``. Then create a file named ``Dockerfile`` in your project directory, +in which you'll extend the official SDK image, copy over your code, and add any custom dependencies. For example: .. code-block:: docker - # Extend the official Rasa SDK image - FROM rasa/rasa-sdk:latest + # Extend the official Rasa SDK image + FROM rasa/rasa-sdk:latest + + # Use subdirectory as working directory + WORKDIR /app + + # Copy any additional custom requirements + COPY actions/requirements-actions.txt ./ + + # Install extra requirements for actions code + RUN pip install -r requirements-actions.txt + + # Copy actions code to working directory + COPY ./actions /app/actions + - # Add a custom system library (e.g. git) - RUN apt-get update && \ - apt-get install -y git +You can then build the image via the following command: - # Add a custom python library (e.g. jupyter) - RUN pip install --no-cache-dir jupyter +.. code-block:: bash + + docker build . -t /: + +The ```` should reference how this image will be different from others. For +example, you could version or date your tags, as well as create different tags that have different code for production +and development servers. You should create a new tag any time you update your code and want to re-deploy it. + +If you are using docker-compose locally, you can use this image directly in your +``docker-compose.yml``: + +.. code-block:: yaml + + version: '3.0' + services: + app: + image: /: -You can then build the image via the following command, and use it in your -``docker-compose.yml`` instead of the ``rasa/rasa-sdk`` image. +If you're building this image to make it available from another server, +for example a Rasa X or Rasa Enterprise deployment, you should push the image to a cloud repository. +You can push the image to DockerHub via: .. code-block:: bash - docker build . -t : + docker login --username --password + docker push /: + +To authenticate and push images to a different container registry, please refer to the documentation of +your chosen container registry. + +Then, reference the new image tag in your ``docker-compose.override.yml``: + +.. code-block:: yaml + + version: '3.0' + services: + app: + image: /: Adding a Custom Tracker Store ***************************** From e9813bf1d091202abdff9d3dfc46de5b68a38840 Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 24 Feb 2020 14:59:19 +0100 Subject: [PATCH 03/27] add changelog --- changelog/5302.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog/5302.doc.rst diff --git a/changelog/5302.doc.rst b/changelog/5302.doc.rst new file mode 100644 index 000000000000..53e9816dd85b --- /dev/null +++ b/changelog/5302.doc.rst @@ -0,0 +1 @@ +Improved documentation on how to build and deploy an action server image for use on other servers such as Rasa X deployments. From 7076d96ff3c5f10f2ea216f673100c761181711a Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 2 Mar 2020 16:14:22 +0100 Subject: [PATCH 04/27] beginnings of splitting up docker info, needs cleanup --- docs/user-guide/docker/building-in-docker.rst | 244 ++++++++ .../user-guide/docker/deploying-in-docker.rst | 302 ++++++++++ docs/user-guide/how-to-deploy.rst | 522 +----------------- 3 files changed, 554 insertions(+), 514 deletions(-) create mode 100644 docs/user-guide/docker/building-in-docker.rst create mode 100644 docs/user-guide/docker/deploying-in-docker.rst diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst new file mode 100644 index 000000000000..2c11b44a8684 --- /dev/null +++ b/docs/user-guide/docker/building-in-docker.rst @@ -0,0 +1,244 @@ +.. _building-in-docker: + +Building an Assistant with Rasa and Docker +========================================== + +If you don't have a Rasa project yet, you can build one in Docker without having to install Rasa Open Source +on your local machine. If you already have a model you're satisfied with, skip ahead to :ref:`running-the-rasa-server` +to deploy your model. + +.. contents:: + :local: + +Installing Docker +***************** + +If you're not sure if you have Docker installed, you can check by running: + + .. code-block:: bash + + docker -v && docker-compose -v + # Docker version 18.09.2, build 6247962 + # docker-compose version 1.23.2, build 1110ad01 + +If Docker is installed on your machine, the output should show you your installed +versions of Docker and Docker Compose. If the command doesn't work, you'll have to +install Docker. +See `Docker Installation `_ for details. + +Setting up your Rasa Project +**************************** + +Just like in the :ref:`tutorial `, you'll use the ``rasa init`` command to create a project. +The only difference is that you'll be running Rasa inside a Docker container, using +the image ``rasa/rasa``. To initialize your project, run: + +.. code-block:: bash + + docker run -v $(pwd):/app rasa/rasa init --no-prompt + +What does this command mean? + +- ``-v $(pwd):/app`` mounts your current working directory to the working directory + in the Docker container. This means that files you create on your computer will be + visible inside the container, and files created in the container will + get synced back to your computer. +- ``rasa/rasa`` is the name of the docker image to run. +- the Docker image has the ``rasa`` command as its entrypoint, which means you don't + have to type ``rasa init``, just ``init`` is enough. + +Running this command will produce a lot of output. What happens is: + +- a Rasa project is created +- an initial model is trained using the project's training data. + +To check that the command completed correctly, look at the contents of your working directory: + +.. code-block:: bash + + ls -1 + +The initial project files should all be there, as well as a ``models`` directory that contains your trained model. + + +.. note:: + + By default Docker runs containers as user ``1001``. Hence, all files created by + these containers will be owned by this user. See the `documentation of docker + `_ + and `docker-compose `_ if you want to + run the containers as a different user. + +Talking to Your Assistant +************************* + +To talk to your newly-trained assistant, run this command: + + +.. code-block:: bash + + docker run -it -v $(pwd):/app rasa/rasa shell + +This will start a shell where you can chat to your assistant. +Note that this command includes the flags ``-it``, which means that you are running +Docker interactively, and you are able to give input via the command line. +For commands which require interactive input, like ``rasa shell`` and ``rasa interactive``, +you need to pass the ``-it`` flags. + + +Customizing your Model +********************** + +Choosing a Tag +############## + +To keep images as small as possible, we publish different tags of the ``rasa/rasa`` image +with different dependencies installed. See :ref:`choosing-a-pipeline` for more information +about depedencies. + +All tags start with a version -- the ``latest`` tag corresponds to the current master build. +The tags are: + +- ``{version}`` +- ``{version}-spacy-en`` +- ``{version}-spacy-de`` +- ``{version}-mitie-en`` +- ``{version}-full`` + +The plain ``{version}`` tag includes all the dependencies you need to run the ``supervised_embeddings`` pipeline. +If you are using components with pre-trained word vectors, you need to choose the corresponding tag. +Alternatively, you can use the ``-full`` tag, which includes all pipeline dependencies. + +.. note:: + + You can see a list of all the versions and tags of the Rasa Docker image + `here `_. + + +.. _model_training_docker: + +Training a Custom Rasa Model with Docker +######################################## + +Edit the ``config.yml`` file to use the pipeline you want, and place +your NLU and Core data into the ``data/`` directory. +Now you can train your Rasa model by running: + +.. code-block:: bash + + docker run \ + -v $(pwd):/app \ + rasa/rasa:latest-full \ + train \ + --domain domain.yml \ + --data data \ + --out models + +Here's what's happening in that command: + + - ``-v $(pwd):/app``: Mounts your project directory into the Docker + container so that Rasa can train a model on your training data + - ``rasa/rasa:latest-full``: Use the Rasa image with the tag ``latest-full`` + - ``train``: Execute the ``rasa train`` command within the container. For more + information see :ref:`command-line-interface`. + +In this case, we've also passed values for the location of the domain file, training +data, and the models output directory to show how these can be customized. +You can also leave these out since we are passing the default values. + +.. note:: + + If you are using a custom NLU component or policy, you have to add the module file to your + Docker container. You can do this by either mounting the file or by including it in your + own custom image (e.g. if the custom component or policy has extra dependencies). Make sure + that your module is in the Python module search path by setting the + environment variable ``PYTHONPATH=$PYTHONPATH:``. + +Adding Custom Actions +********************* + +To create more sophisticated assistants, you will want to use :ref:`custom-actions`. +Continuing the example from above, you might want to add an action which tells +the user a joke to cheer them up. + +Running a Custom Action in Docker-Compose +######################################### + +Start by creating the custom actions in a directory ``actions``: + +.. code-block:: bash + + mkdir actions + # Rasa SDK expects a python module. + # Therefore, make sure that you have this file in the directory. + touch actions/__init__.py + touch actions/actions.py + +Then build a custom action using the Rasa SDK, e.g.: + +.. code-block:: python + + import requests + import json + from rasa_sdk import Action + + + class ActionJoke(Action): + def name(self): + return "action_joke" + + def run(self, dispatcher, tracker, domain): + request = requests.get('http://api.icndb.com/jokes/random').json() # make an api call + joke = request['value']['joke'] # extract a joke from returned json response + dispatcher.utter_message(text=joke) # send the message back to the user + return [] + +Next, add the custom action in your stories and your domain file. +Continuing with the example bot from ``rasa init``, replace ``utter_cheer_up`` in +``data/stories.md`` with the custom action ``action_joke``, and add +``action_joke`` to the actions in the domain file. + +To instruct Rasa to use the action server you have to tell Rasa its location. +Add this to your ``endpoints.yml`` (if it does not exist, create it): + +.. code-block:: yaml + + action_endpoint: + url: http://app:5055/webhook + +To spin up the action server together with the Rasa instance, add a service +``app`` to the ``docker-compose.yml``: + +.. code-block:: yaml + :emphasize-lines: 11-14 + + version: '3.0' + services: + rasa: + image: rasa/rasa:latest-full + ports: + - 5005:5005 + volumes: + - ./:/app + command: + - run + app: + image: rasa/rasa-sdk:latest + volumes: + - ./actions:/app/actions + +This pulls the image for the Rasa SDK which includes the action server, +mounts your custom actions into it, and starts the server. + +Run ``docker-compose up`` to start the action server together with Rasa. + +.. warning:: + + If you create a more complicated + action that has extra library dependencies, you will need to + :ref:`build an action server image` to run your code. + +Deploying your Model +#################### + +Once you're happy with your model, you can \ No newline at end of file diff --git a/docs/user-guide/docker/deploying-in-docker.rst b/docs/user-guide/docker/deploying-in-docker.rst new file mode 100644 index 000000000000..653dddb87836 --- /dev/null +++ b/docs/user-guide/docker/deploying-in-docker.rst @@ -0,0 +1,302 @@ +.. _deploying-rasa-in-docker-compose: + +Deploying a Rasa Assistant in Docker-Compose +============================================ + +.. contents:: + :local: + :depth: 2 + +.. _running-the-rasa-server: + + +Installing Docker +~~~~~~~~~~~~~~~~~ + +If you're not sure if you have Docker installed, you can check by running: + + .. code-block:: bash + + docker -v && docker-compose -v + # Docker version 18.09.2, build 6247962 + # docker-compose version 1.23.2, build 1110ad01 + +If Docker is installed on your machine, the output should show you your installed +versions of Docker and Docker Compose. If the command doesn't work, you'll have to +install Docker. +See `Docker Installation `_ for details. + + +Running the Rasa Server +~~~~~~~~~~~~~~~~~~~~~~~ + +To run your AI assistant in production, configure your required +:ref:`messaging-and-voice-channels` in ``credentials.yml``. If this file does not +exist, create it using: + +.. code-block:: bash + + touch credentials.yml + +Then edit it according to your connected channels. +After, run the trained model with: + +.. code-block:: bash + + docker run \ + -v $(pwd)/models:/app/models \ + rasa/rasa:latest-full \ + run + +Command Description: + + - ``-v $(pwd)/models:/app/models``: Mounts the directory with the trained Rasa model + in the container + - ``rasa/rasa:latest-full``: Use the Rasa image with the tag ``latest-full`` + - ``run``: Executes the ``rasa run`` command. For more information see + :ref:`command-line-interface`. + + +Using Docker Compose to Run Multiple Services +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To run Rasa together with other services, such as a server for custom actions, it is +recommend to use `Docker Compose `_. +Docker Compose provides an easy way to run multiple containers together without +having to run multiple commands. + +.. contents:: + :local: + :depth: 2 + +Start by creating a file called ``docker-compose.yml``: + +.. code-block:: bash + + touch docker-compose.yml + +Add the following content to the file: + +.. code-block:: yaml + + version: '3.0' + services: + rasa: + image: rasa/rasa:latest-full + ports: + - 5005:5005 + volumes: + - ./:/app + command: + - run + + +The file starts with the version of the Docker Compose specification that you +want to use. +Each container is declared as a ``service`` within the docker-compose file. +The first service is the ``rasa`` service. + +The command is similar to the ``docker run`` command. +The ``ports`` part defines a port mapping between the container and your host +system. In this case it makes ``5005`` of the ``rasa`` service available on +port ``5005`` of your host. +This is the port of the :ref:`REST Channel ` interface of Rasa. + +.. note:: + + Since Docker Compose starts a set of Docker containers, it is no longer + possible to connect to the command line of a single container after executing the + ``run`` command. + +To run the services configured in your ``docker-compose.yml`` execute: + +.. code-block:: bash + + docker-compose up + + + + +.. _building-an-action-server-image: + +Deploying an Action Server Image +******************************** + +If you build an image that includes your action code and store it in a container registry, you can run it locally +or as part of your Rasa X or Rasa Enterprise deployment, without having to move code between servers. +In addition, you can add any additional dependencies of systems or Python libraries +that are part of your action code but not included in the base ``rasa/rasa-sdk`` image. + +This documentation assumes you are pushing your images to `DockerHub `_. +DockerHub will let you host multiple public repositories and +one private repository for free. Be sure to first `create an account `_ +and `create a repository `_ to store your images. You could also push images to +a different Docker registry, such as `Google Container Registry `_, +`Amazon Elastic Container Registry `_, or +`Azure Container Registry `_. + +To create your image, first create a list of your custom actions requirements in a file, +``actions/requirements-actions.txt``. Then create a file named ``Dockerfile`` in your project directory, +in which you'll extend the official SDK image, copy over your code, and add any custom dependencies. For example: + +.. code-block:: docker + + # Extend the official Rasa SDK image + FROM rasa/rasa-sdk:latest + + # Use subdirectory as working directory + WORKDIR /app + + # Copy any additional custom requirements + COPY actions/requirements-actions.txt ./ + + # Install extra requirements for actions code + RUN pip install -r requirements-actions.txt + + # Copy actions code to working directory + COPY ./actions /app/actions + + +You can then build the image via the following command: + +.. code-block:: bash + + docker build . -t /: + +The ```` should reference how this image will be different from others. For +example, you could version or date your tags, as well as create different tags that have different code for production +and development servers. You should create a new tag any time you update your code and want to re-deploy it. + +If you are using docker-compose locally, you can use this image directly in your +``docker-compose.yml``: + +.. code-block:: yaml + + version: '3.0' + services: + app: + image: /: + +If you're building this image to make it available from another server, +for example a Rasa X or Rasa Enterprise deployment, you should push the image to a cloud repository. +You can push the image to DockerHub via: + +.. code-block:: bash + + docker login --username --password + docker push /: + +To authenticate and push images to a different container registry, please refer to the documentation of +your chosen container registry. + +Then, reference the new image tag in your ``docker-compose.override.yml``: + +.. code-block:: yaml + + version: '3.0' + services: + app: + image: /: + +Adding a Custom Tracker Store +***************************** + +By default, all conversations are saved in memory. This means that all +conversations are lost as soon as you restart the Rasa server. +If you want to persist your conversations, you can use a different +:ref:`Tracker Store `. + +.. contents:: + :local: + :depth: 2 + +Using PostgreSQL as Tracker Store +################################# + +Start by adding PostgreSQL to your docker-compose file: + +.. code-block:: yaml + + postgres: + image: postgres:latest + +Then add PostgreSQL to the ``tracker_store`` section of your endpoint +configuration ``config/endpoints.yml``: + +.. code-block:: yaml + + tracker_store: + type: sql + dialect: "postgresql" + url: postgres + db: rasa + +Using MongoDB as Tracker Store +############################## + +Start by adding MongoDB to your docker-compose file. The following example +adds the MongoDB as well as a UI (you can skip this), which will be available +at ``localhost:8081``. Username and password for the MongoDB instance are +specified as ``rasa`` and ``example``. + +.. code-block:: yaml + + mongo: + image: mongo + environment: + MONGO_INITDB_ROOT_USERNAME: rasa + MONGO_INITDB_ROOT_PASSWORD: example + mongo-express: + image: mongo-express + ports: + - 8081:8081 + environment: + ME_CONFIG_MONGODB_ADMINUSERNAME: rasa + ME_CONFIG_MONGODB_ADMINPASSWORD: example + +Then add the MongoDB to the ``tracker_store`` section of your endpoints +configuration ``endpoints.yml``: + +.. code-block:: yaml + + tracker_store: + type: mongod + url: mongodb://mongo:27017 + username: rasa + password: example + +Then start all components with ``docker-compose up``. + +Using Redis as Tracker Store +############################## + +Start by adding Redis to your docker-compose file: + +.. code-block:: yaml + + redis: + image: redis:latest + +Then add Redis to the ``tracker_store`` section of your endpoint +configuration ``endpoints.yml``: + +.. code-block:: yaml + + tracker_store: + type: redis + url: redis + +Using a Custom Tracker Store Implementation +########################################### + +If you have a custom implementation of a tracker store you have two options +to add this store to Rasa: + + - extending the Rasa image + - mounting it as volume + +Then add the required configuration to your endpoint configuration +``endpoints.yml`` as it is described in :ref:`tracker-stores`. +If you want the tracker store component (e.g. a certain database) to be part +of your Docker Compose file, add a corresponding service and configuration +there. diff --git a/docs/user-guide/how-to-deploy.rst b/docs/user-guide/how-to-deploy.rst index 6e78999fd04b..24f15bfeeaab 100644 --- a/docs/user-guide/how-to-deploy.rst +++ b/docs/user-guide/how-to-deploy.rst @@ -51,519 +51,13 @@ Docker Compose Rasa-Only Deployment with Docker Compose ---------------------------------------- -It is also possible to deploy a Rasa assistant using Docker Compose without Rasa X. +It is also possible to deploy a Rasa assistant using Docker-Compose without Rasa X. To do so, you can build your +Rasa Assistant :ref:`locally` or :ref:`in Docker`. Then you can +:ref:`deploy your model in Docker-Compose`. -.. contents:: - :local: - :depth: 2 - - -Installing Docker -~~~~~~~~~~~~~~~~~ - -If you're not sure if you have Docker installed, you can check by running: - - .. code-block:: bash - - docker -v && docker-compose -v - # Docker version 18.09.2, build 6247962 - # docker-compose version 1.23.2, build 1110ad01 - -If Docker is installed on your machine, the output should show you your installed -versions of Docker and Docker Compose. If the command doesn't work, you'll have to -install Docker. -See `Docker Installation `_ for details. - -Building an Assistant with Rasa and Docker -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you don't have a Rasa project yet, you can build one in Docker without having to install Rasa Open Source -on your local machine. If you already have a model you're satisfied with, skip ahead to :ref:`running-the-rasa-server` -to deploy your model. - -.. contents:: - :local: - :depth: 2 - - -Setting up your Rasa Project -**************************** - -Just like in the :ref:`tutorial `, you'll use the ``rasa init`` command to create a project. -The only difference is that you'll be running Rasa inside a Docker container, using -the image ``rasa/rasa``. To initialize your project, run: - -.. code-block:: bash - - docker run -v $(pwd):/app rasa/rasa init --no-prompt - -What does this command mean? - -- ``-v $(pwd):/app`` mounts your current working directory to the working directory - in the Docker container. This means that files you create on your computer will be - visible inside the container, and files created in the container will - get synced back to your computer. -- ``rasa/rasa`` is the name of the docker image to run. -- the Docker image has the ``rasa`` command as its entrypoint, which means you don't - have to type ``rasa init``, just ``init`` is enough. - -Running this command will produce a lot of output. What happens is: - -- a Rasa project is created -- an initial model is trained using the project's training data. - -To check that the command completed correctly, look at the contents of your working directory: - -.. code-block:: bash - - ls -1 - -The initial project files should all be there, as well as a ``models`` directory that contains your trained model. - - -.. note:: - - By default Docker runs containers as user ``1001``. Hence, all files created by - these containers will be owned by this user. See the `documentation of docker - `_ - and `docker-compose `_ if you want to - run the containers as a different user. - -Talking to Your Assistant -************************* - -To talk to your newly-trained assistant, run this command: - - -.. code-block:: bash - - docker run -it -v $(pwd):/app rasa/rasa shell - -This will start a shell where you can chat to your assistant. -Note that this command includes the flags ``-it``, which means that you are running -Docker interactively, and you are able to give input via the command line. -For commands which require interactive input, like ``rasa shell`` and ``rasa interactive``, -you need to pass the ``-it`` flags. - - -Customizing your Model -********************** - -Choosing a Tag -############## - -To keep images as small as possible, we publish different tags of the ``rasa/rasa`` image -with different dependencies installed. See :ref:`choosing-a-pipeline` for more information -about depedencies. - -All tags start with a version -- the ``latest`` tag corresponds to the current master build. -The tags are: - -- ``{version}`` -- ``{version}-spacy-en`` -- ``{version}-spacy-de`` -- ``{version}-mitie-en`` -- ``{version}-full`` - -The plain ``{version}`` tag includes all the dependencies you need to run the ``supervised_embeddings`` pipeline. -If you are using components with pre-trained word vectors, you need to choose the corresponding tag. -Alternatively, you can use the ``-full`` tag, which includes all pipeline dependencies. - -.. note:: - - You can see a list of all the versions and tags of the Rasa Docker image - `here `_. - - -.. _model_training_docker: - -Training a Custom Rasa Model with Docker -######################################## - -Edit the ``config.yml`` file to use the pipeline you want, and place -your NLU and Core data into the ``data/`` directory. -Now you can train your Rasa model by running: - -.. code-block:: bash - - docker run \ - -v $(pwd):/app \ - rasa/rasa:latest-full \ - train \ - --domain domain.yml \ - --data data \ - --out models - -Here's what's happening in that command: - - - ``-v $(pwd):/app``: Mounts your project directory into the Docker - container so that Rasa can train a model on your training data - - ``rasa/rasa:latest-full``: Use the Rasa image with the tag ``latest-full`` - - ``train``: Execute the ``rasa train`` command within the container. For more - information see :ref:`command-line-interface`. - -In this case, we've also passed values for the location of the domain file, training -data, and the models output directory to show how these can be customized. -You can also leave these out since we are passing the default values. - -.. note:: - - If you are using a custom NLU component or policy, you have to add the module file to your - Docker container. You can do this by either mounting the file or by including it in your - own custom image (e.g. if the custom component or policy has extra dependencies). Make sure - that your module is in the Python module search path by setting the - environment variable ``PYTHONPATH=$PYTHONPATH:``. - -.. _running-the-rasa-server: - -Running the Rasa Server -~~~~~~~~~~~~~~~~~~~~~~~ - -To run your AI assistant in production, configure your required -:ref:`messaging-and-voice-channels` in ``credentials.yml``. If this file does not -exist, create it using: - -.. code-block:: bash - - touch credentials.yml - -Then edit it according to your connected channels. -After, run the trained model with: - -.. code-block:: bash - - docker run \ - -v $(pwd)/models:/app/models \ - rasa/rasa:latest-full \ - run - -Command Description: - - - ``-v $(pwd)/models:/app/models``: Mounts the directory with the trained Rasa model - in the container - - ``rasa/rasa:latest-full``: Use the Rasa image with the tag ``latest-full`` - - ``run``: Executes the ``rasa run`` command. For more information see - :ref:`command-line-interface`. - - -Using Docker Compose to Run Multiple Services -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To run Rasa together with other services, such as a server for custom actions, it is -recommend to use `Docker Compose `_. -Docker Compose provides an easy way to run multiple containers together without -having to run multiple commands. - -.. contents:: - :local: - :depth: 2 - -Start by creating a file called ``docker-compose.yml``: - -.. code-block:: bash - - touch docker-compose.yml - -Add the following content to the file: - -.. code-block:: yaml - - version: '3.0' - services: - rasa: - image: rasa/rasa:latest-full - ports: - - 5005:5005 - volumes: - - ./:/app - command: - - run - - -The file starts with the version of the Docker Compose specification that you -want to use. -Each container is declared as a ``service`` within the docker-compose file. -The first service is the ``rasa`` service. - -The command is similar to the ``docker run`` command. -The ``ports`` part defines a port mapping between the container and your host -system. In this case it makes ``5005`` of the ``rasa`` service available on -port ``5005`` of your host. -This is the port of the :ref:`REST Channel ` interface of Rasa. - -.. note:: - - Since Docker Compose starts a set of Docker containers, it is no longer - possible to connect to the command line of a single container after executing the - ``run`` command. - -To run the services configured in your ``docker-compose.yml`` execute: - -.. code-block:: bash - - docker-compose up - - -Adding Custom Actions -********************* - -To create more sophisticated assistants, you will want to use :ref:`custom-actions`. -Continuing the example from above, you might want to add an action which tells -the user a joke to cheer them up. - -Running a Custom Action in Docker-Compose -######################################### - -Start by creating the custom actions in a directory ``actions``: - -.. code-block:: bash - - mkdir actions - # Rasa SDK expects a python module. - # Therefore, make sure that you have this file in the directory. - touch actions/__init__.py - touch actions/actions.py - -Then build a custom action using the Rasa SDK, e.g.: - -.. code-block:: python - - import requests - import json - from rasa_sdk import Action - - - class ActionJoke(Action): - def name(self): - return "action_joke" - - def run(self, dispatcher, tracker, domain): - request = requests.get('http://api.icndb.com/jokes/random').json() # make an api call - joke = request['value']['joke'] # extract a joke from returned json response - dispatcher.utter_message(text=joke) # send the message back to the user - return [] - -Next, add the custom action in your stories and your domain file. -Continuing with the example bot from ``rasa init``, replace ``utter_cheer_up`` in -``data/stories.md`` with the custom action ``action_joke``, and add -``action_joke`` to the actions in the domain file. - -To instruct Rasa to use the action server you have to tell Rasa its location. -Add this to your ``endpoints.yml`` (if it does not exist, create it): - -.. code-block:: yaml - - action_endpoint: - url: http://app:5055/webhook - -To spin up the action server together with the Rasa instance, add a service -``app`` to the ``docker-compose.yml``: - -.. code-block:: yaml - :emphasize-lines: 11-14 - - version: '3.0' - services: - rasa: - image: rasa/rasa:latest-full - ports: - - 5005:5005 - volumes: - - ./:/app - command: - - run - app: - image: rasa/rasa-sdk:latest - volumes: - - ./actions:/app/actions - -This pulls the image for the Rasa SDK which includes the action server, -mounts your custom actions into it, and starts the server. - -Run ``docker-compose up`` to start the action server together with Rasa. - -.. warning:: - - If you create a more complicated - action that has extra library dependencies, you will need to - :ref:`build an action server image` to run your code. - -.. _building-an-action-server-image: - -Deploying an Action Server Image -################################ - -If you build an image that includes your action code and store it in a container registry, you can run it locally -or as part of your Rasa X or Rasa Enterprise deployment, without having to move code between servers. -In addition, you can add any additional dependencies of systems or Python libraries -that are part of your action code but not included in the base ``rasa/rasa-sdk`` image. - -This documentation assumes you are pushing your images to `DockerHub `_. -DockerHub will let you host multiple public repositories and -one private repository for free. Be sure to first `create an account `_ -and `create a repository `_ to store your images. You could also push images to -a different Docker registry, such as `Google Container Registry `_, -`Amazon Elastic Container Registry `_, or -`Azure Container Registry `_. - -To create your image, first create a list of your custom actions requirements in a file, -``actions/requirements-actions.txt``. Then create a file named ``Dockerfile`` in your project directory, -in which you'll extend the official SDK image, copy over your code, and add any custom dependencies. For example: - -.. code-block:: docker - - # Extend the official Rasa SDK image - FROM rasa/rasa-sdk:latest - - # Use subdirectory as working directory - WORKDIR /app - - # Copy any additional custom requirements - COPY actions/requirements-actions.txt ./ - - # Install extra requirements for actions code - RUN pip install -r requirements-actions.txt - - # Copy actions code to working directory - COPY ./actions /app/actions - - -You can then build the image via the following command: - -.. code-block:: bash - - docker build . -t /: - -The ```` should reference how this image will be different from others. For -example, you could version or date your tags, as well as create different tags that have different code for production -and development servers. You should create a new tag any time you update your code and want to re-deploy it. - -If you are using docker-compose locally, you can use this image directly in your -``docker-compose.yml``: - -.. code-block:: yaml - - version: '3.0' - services: - app: - image: /: - -If you're building this image to make it available from another server, -for example a Rasa X or Rasa Enterprise deployment, you should push the image to a cloud repository. -You can push the image to DockerHub via: - -.. code-block:: bash - - docker login --username --password - docker push /: - -To authenticate and push images to a different container registry, please refer to the documentation of -your chosen container registry. - -Then, reference the new image tag in your ``docker-compose.override.yml``: - -.. code-block:: yaml - - version: '3.0' - services: - app: - image: /: - -Adding a Custom Tracker Store -***************************** - -By default, all conversations are saved in memory. This means that all -conversations are lost as soon as you restart the Rasa server. -If you want to persist your conversations, you can use a different -:ref:`Tracker Store `. - -Using PostgreSQL as Tracker Store -################################# - -Start by adding PostgreSQL to your docker-compose file: - -.. code-block:: yaml - - postgres: - image: postgres:latest - -Then add PostgreSQL to the ``tracker_store`` section of your endpoint -configuration ``config/endpoints.yml``: - -.. code-block:: yaml - - tracker_store: - type: sql - dialect: "postgresql" - url: postgres - db: rasa - -Using MongoDB as Tracker Store -############################## - -Start by adding MongoDB to your docker-compose file. The following example -adds the MongoDB as well as a UI (you can skip this), which will be available -at ``localhost:8081``. Username and password for the MongoDB instance are -specified as ``rasa`` and ``example``. - -.. code-block:: yaml - - mongo: - image: mongo - environment: - MONGO_INITDB_ROOT_USERNAME: rasa - MONGO_INITDB_ROOT_PASSWORD: example - mongo-express: - image: mongo-express - ports: - - 8081:8081 - environment: - ME_CONFIG_MONGODB_ADMINUSERNAME: rasa - ME_CONFIG_MONGODB_ADMINPASSWORD: example - -Then add the MongoDB to the ``tracker_store`` section of your endpoints -configuration ``endpoints.yml``: - -.. code-block:: yaml - - tracker_store: - type: mongod - url: mongodb://mongo:27017 - username: rasa - password: example - -Then start all components with ``docker-compose up``. - -Using Redis as Tracker Store -############################## - -Start by adding Redis to your docker-compose file: - -.. code-block:: yaml - - redis: - image: redis:latest - -Then add Redis to the ``tracker_store`` section of your endpoint -configuration ``endpoints.yml``: - -.. code-block:: yaml - - tracker_store: - type: redis - url: redis - -Using a Custom Tracker Store Implementation -########################################### - -If you have a custom implementation of a tracker store you have two options -to add this store to Rasa: - - - extending the Rasa image - - mounting it as volume +.. toctree:: + :titlesonly: + :maxdepth: 1 -Then add the required configuration to your endpoint configuration -``endpoints.yml`` as it is described in :ref:`tracker-stores`. -If you want the tracker store component (e.g. a certain database) to be part -of your Docker Compose file, add a corresponding service and configuration -there. + docker/building-in-docker + docker/deploying-in-docker From 9e9f9ce7cd7ee92c3f46ef038dff0f424d8996e7 Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 2 Mar 2020 16:14:39 +0100 Subject: [PATCH 05/27] clean up tracker store docs code formatting --- docs/api/tracker-stores.rst | 44 ++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/api/tracker-stores.rst b/docs/api/tracker-stores.rst index c236bea782d8..d090c84b78c2 100644 --- a/docs/api/tracker-stores.rst +++ b/docs/api/tracker-stores.rst @@ -1,5 +1,5 @@ :desc: All conversations are stored within a tracker store. Read how open source - library Rasa Core provides implementations for different store types out + library Rasa provides implementations for different store types out of the box. .. _tracker-stores: @@ -9,9 +9,9 @@ Tracker Stores .. edit-link:: -All conversations are stored within a `tracker store`. -Rasa Core provides implementations for different store types out of the box. -If you want to use another store, you can also build a custom tracker store by extending the `TrackerStore` class. +All conversations are stored within a tracker store. +Rasa provides implementations for different store types out of the box. +If you want to use another store, you can also build a custom tracker store by extending the ``TrackerStore`` class. .. contents:: @@ -19,13 +19,13 @@ InMemoryTrackerStore (default) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :Description: - `InMemoryTrackerStore` is the default tracker store. It is used if no other tracker store is configured. + ``InMemoryTrackerStore`` is the default tracker store. It is used if no other tracker store is configured. It stores the conversation history in memory. - .. note:: As this store keeps all history in memory the entire history is lost if you restart Rasa Core. + .. note:: As this store keeps all history in memory, the entire history is lost if you restart Rasa. :Configuration: - To use the `InMemoryTrackerStore` no configuration is needed. + To use the ``InMemoryTrackerStore`` no configuration is needed. .. _sql-tracker-store: @@ -38,9 +38,9 @@ SQLTrackerStore intent name and typename :Configuration: - To set up Rasa Core with SQL the following steps are required: + To set up Rasa with SQL the following steps are required: - 1. Add required configuration to your `endpoints.yml` + 1. Add required configuration to your ``endpoints.yml``: .. code-block:: yaml @@ -54,7 +54,7 @@ SQLTrackerStore query: # optional dictionary to be added as a query string to the connection URL driver: my-driver - 3. To start the Rasa Core server using your SQL backend, + 3. To start the Rasa server using your SQL backend, add the ``--endpoints`` flag, e.g.: .. code-block:: bash @@ -69,7 +69,7 @@ SQLTrackerStore - ``username`` (default: ``None``): The username which is used for authentication - ``password`` (default: ``None``): The password which is used for authentication - ``event_broker`` (default: ``None``): Event broker to publish events to - - ``login_db`` (default: ``None``): Alternative database name to which initially connect, and create the database specified by `db` (PostgreSQL only) + - ``login_db`` (default: ``None``): Alternative database name to which initially connect, and create the database specified by ``db`` (PostgreSQL only) - ``query`` (default: ``None``): Dictionary of options to be passed to the dialect and/or the DBAPI upon connect @@ -127,14 +127,14 @@ RedisTrackerStore ~~~~~~~~~~~~~~~~~~ :Description: - `RedisTrackerStore` can be used to store the conversation history in `Redis `_. + ``RedisTrackerStore`` can be used to store the conversation history in `Redis `_. Redis is a fast in-memory key-value store which can optionally also persist data. :Configuration: - To set up Rasa Core with Redis the following steps are required: + To set up Rasa with Redis the following steps are required: 1. Start your Redis instance - 2. Add required configuration to your `endpoints.yml` + 2. Add required configuration to your ``endpoints.yml``: .. code-block:: yaml @@ -146,8 +146,8 @@ RedisTrackerStore password: use_ssl: - 3. To start the Rasa Core server using your configured Redis instance, - add the :code:`--endpoints` flag, e.g.: + 3. To start the Rasa server using your configured Redis instance, + add the ``--endpoints`` flag, e.g.: .. code-block:: bash @@ -165,12 +165,12 @@ MongoTrackerStore ~~~~~~~~~~~~~~~~~ :Description: - `MongoTrackerStore` can be used to store the conversation history in `Mongo `_. + ``MongoTrackerStore`` can be used to store the conversation history in `Mongo `_. MongoDB is a free and open-source cross-platform document-oriented NoSQL database. :Configuration: 1. Start your MongoDB instance. - 2. Add required configuration to your `endpoints.yml` + 2. Add required configuration to your ``endpoints.yml`` .. code-block:: yaml @@ -185,7 +185,7 @@ MongoTrackerStore You can also add more advanced configurations (like enabling ssl) by appending a parameter to the url field, e.g. mongodb://localhost:27017/?ssl=true - 3. To start the Rasa Core server using your configured MongoDB instance, + 3. To start the Rasa server using your configured MongoDB instance, add the :code:`--endpoints` flag, e.g.: .. code-block:: bash @@ -205,14 +205,14 @@ Custom Tracker Store :Description: If you require a tracker store which is not available out of the box, you can implement your own. - This is done by extending the base class `TrackerStore`. + This is done by extending the base class ``TrackerStore``. .. autoclass:: rasa.core.tracker_store.TrackerStore :Steps: - 1. Extend the `TrackerStore` base class. Note that your constructor has to + 1. Extend the ``TrackerStore`` base class. Note that your constructor has to provide a parameter ``url``. - 2. In your endpoints.yml put in the module path to your custom tracker store + 2. In your ``endpoints.yml`` put in the module path to your custom tracker store and the parameters you require: .. code-block:: yaml From da7246506413978f1d1427a3c5c3a33ebb3753e3 Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 16 Mar 2020 15:53:12 +0100 Subject: [PATCH 06/27] implement some of my changes --- docs/user-guide/docker/building-in-docker.rst | 50 +++++++++++-------- .../user-guide/docker/deploying-in-docker.rst | 32 ++++++++++-- 2 files changed, 57 insertions(+), 25 deletions(-) diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index 2c11b44a8684..c551e0d95fa2 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -4,8 +4,8 @@ Building an Assistant with Rasa and Docker ========================================== If you don't have a Rasa project yet, you can build one in Docker without having to install Rasa Open Source -on your local machine. If you already have a model you're satisfied with, skip ahead to :ref:`running-the-rasa-server` -to deploy your model. +on your local machine. If you already have a model you're satisfied with, skip ahead to +:ref:`deploying-rasa-in-docker-compose` to deploy your model. .. contents:: :local: @@ -161,20 +161,18 @@ To create more sophisticated assistants, you will want to use :ref:`custom-actio Continuing the example from above, you might want to add an action which tells the user a joke to cheer them up. -Running a Custom Action in Docker-Compose -######################################### - -Start by creating the custom actions in a directory ``actions``: +Start by creating the custom actions in a directory ``actions`` in your working directory: .. code-block:: bash mkdir actions + mv actions.py actions/actions.py # Rasa SDK expects a python module. # Therefore, make sure that you have this file in the directory. touch actions/__init__.py - touch actions/actions.py -Then build a custom action using the Rasa SDK, e.g.: + +Then build a custom action using the Rasa SDK by editing ``actions/actions.py``, e.g.: .. code-block:: python @@ -193,19 +191,33 @@ Then build a custom action using the Rasa SDK, e.g.: dispatcher.utter_message(text=joke) # send the message back to the user return [] -Next, add the custom action in your stories and your domain file. -Continuing with the example bot from ``rasa init``, replace ``utter_cheer_up`` in -``data/stories.md`` with the custom action ``action_joke``, and add -``action_joke`` to the actions in the domain file. +To tell your bot to use this new action, replace ``utter_cheer_up`` in +``data/stories.md`` with the custom action ``action_joke``. + +In ``domain.yml``, add a section for custom actions, including your new action: + +.. code-block:: yaml + + actions: + - action_joke To instruct Rasa to use the action server you have to tell Rasa its location. -Add this to your ``endpoints.yml`` (if it does not exist, create it): +Add this to your ``endpoints.yml``: .. code-block:: yaml action_endpoint: url: http://app:5055/webhook +After updating your domain and stories, you have to retrain your model: + +.. code-block:: bash + + docker run \ + -v $(pwd):/app \ + rasa/rasa:latest-full \ + train + To spin up the action server together with the Rasa instance, add a service ``app`` to the ``docker-compose.yml``: @@ -232,13 +244,11 @@ mounts your custom actions into it, and starts the server. Run ``docker-compose up`` to start the action server together with Rasa. -.. warning:: - - If you create a more complicated - action that has extra library dependencies, you will need to - :ref:`build an action server image` to run your code. Deploying your Model -#################### +******************** -Once you're happy with your model, you can \ No newline at end of file +Work on your bot until you have a minimum viable assistant that can handle your happy paths. After +that, you'll want to deploy your model to get feedback from real test users. To do so, you can deploy the +model you created with Rasa X via one of our :ref:`recommended deployment methods`. +Or, you can do a :ref:`Rasa-only deployment in Docker-Compose`. \ No newline at end of file diff --git a/docs/user-guide/docker/deploying-in-docker.rst b/docs/user-guide/docker/deploying-in-docker.rst index 653dddb87836..5da740a78979 100644 --- a/docs/user-guide/docker/deploying-in-docker.rst +++ b/docs/user-guide/docker/deploying-in-docker.rst @@ -7,8 +7,6 @@ Deploying a Rasa Assistant in Docker-Compose :local: :depth: 2 -.. _running-the-rasa-server: - Installing Docker ~~~~~~~~~~~~~~~~~ @@ -26,6 +24,7 @@ versions of Docker and Docker Compose. If the command doesn't work, you'll have install Docker. See `Docker Installation `_ for details. +.. _running-the-rasa-server: Running the Rasa Server ~~~~~~~~~~~~~~~~~~~~~~~ @@ -108,14 +107,31 @@ This is the port of the :ref:`REST Channel ` interface of Rasa. possible to connect to the command line of a single container after executing the ``run`` command. -To run the services configured in your ``docker-compose.yml`` execute: -.. code-block:: bash +To add the action server, add the image of your action server code. To learn how to deploy +an action server image, see :ref:`building-an-action-server-image`. - docker-compose up +.. code-block:: yaml + :emphasize-lines: 11-14 + + version: '3.0' + services: + rasa: + image: rasa/rasa:latest-full + ports: + - 5005:5005 + volumes: + - ./:/app + command: + - run + app: + image: +To run the services configured in your ``docker-compose.yml`` execute: +.. code-block:: bash + docker-compose up .. _building-an-action-server-image: @@ -150,12 +166,18 @@ in which you'll extend the official SDK image, copy over your code, and add any # Copy any additional custom requirements COPY actions/requirements-actions.txt ./ + # Change back to root user to install dependencies + USER root + # Install extra requirements for actions code RUN pip install -r requirements-actions.txt # Copy actions code to working directory COPY ./actions /app/actions + # By best practices, don't run the code with root user + USER 1001 + You can then build the image via the following command: From 7fe732bb793c891a8a88a3a27e88f50e2a725c0d Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 16 Mar 2020 15:57:06 +0100 Subject: [PATCH 07/27] rasa open source --- docs/api/tracker-stores.rst | 13 ++++++------- docs/user-guide/docker/building-in-docker.rst | 4 ++-- docs/user-guide/docker/deploying-in-docker.rst | 2 +- 3 files changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/api/tracker-stores.rst b/docs/api/tracker-stores.rst index d090c84b78c2..9fa7db15674f 100644 --- a/docs/api/tracker-stores.rst +++ b/docs/api/tracker-stores.rst @@ -1,6 +1,5 @@ -:desc: All conversations are stored within a tracker store. Read how open source - library Rasa provides implementations for different store types out - of the box. +:desc: All conversations are stored within a tracker store. Read how Rasa Open Source + provides implementations for different store types out of the box. .. _tracker-stores: @@ -10,7 +9,7 @@ Tracker Stores .. edit-link:: All conversations are stored within a tracker store. -Rasa provides implementations for different store types out of the box. +Rasa Open Source provides implementations for different store types out of the box. If you want to use another store, you can also build a custom tracker store by extending the ``TrackerStore`` class. .. contents:: @@ -22,7 +21,7 @@ InMemoryTrackerStore (default) ``InMemoryTrackerStore`` is the default tracker store. It is used if no other tracker store is configured. It stores the conversation history in memory. - .. note:: As this store keeps all history in memory, the entire history is lost if you restart Rasa. + .. note:: As this store keeps all history in memory, the entire history is lost if you restart the Rasa server. :Configuration: To use the ``InMemoryTrackerStore`` no configuration is needed. @@ -38,7 +37,7 @@ SQLTrackerStore intent name and typename :Configuration: - To set up Rasa with SQL the following steps are required: + To set up Rasa Open Source with SQL the following steps are required: 1. Add required configuration to your ``endpoints.yml``: @@ -131,7 +130,7 @@ RedisTrackerStore Redis is a fast in-memory key-value store which can optionally also persist data. :Configuration: - To set up Rasa with Redis the following steps are required: + To set up Rasa Open Source with Redis the following steps are required: 1. Start your Redis instance 2. Add required configuration to your ``endpoints.yml``: diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index c551e0d95fa2..762c84b9d511 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -201,7 +201,7 @@ In ``domain.yml``, add a section for custom actions, including your new action: actions: - action_joke -To instruct Rasa to use the action server you have to tell Rasa its location. +To instruct the Rasa server to use the action server, you have to tell Rasa its location. Add this to your ``endpoints.yml``: .. code-block:: yaml @@ -242,7 +242,7 @@ To spin up the action server together with the Rasa instance, add a service This pulls the image for the Rasa SDK which includes the action server, mounts your custom actions into it, and starts the server. -Run ``docker-compose up`` to start the action server together with Rasa. +Run ``docker-compose up`` to start the action server together with the Rasa server. Deploying your Model diff --git a/docs/user-guide/docker/deploying-in-docker.rst b/docs/user-guide/docker/deploying-in-docker.rst index 5da740a78979..0e1fec92e0fd 100644 --- a/docs/user-guide/docker/deploying-in-docker.rst +++ b/docs/user-guide/docker/deploying-in-docker.rst @@ -312,7 +312,7 @@ Using a Custom Tracker Store Implementation ########################################### If you have a custom implementation of a tracker store you have two options -to add this store to Rasa: +to add this store to Rasa Open Source: - extending the Rasa image - mounting it as volume From dccfd754eb6e0a8331f382411dbd8c310877de9c Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 16 Mar 2020 16:11:33 +0100 Subject: [PATCH 08/27] review comments, improve links --- docs/user-guide/docker/building-in-docker.rst | 4 ++-- .../user-guide/docker/deploying-in-docker.rst | 2 +- docs/user-guide/how-to-deploy.rst | 19 ++++++++++--------- 3 files changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index 762c84b9d511..e2d5c6b8ab84 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -1,7 +1,7 @@ .. _building-in-docker: -Building an Assistant with Rasa and Docker -========================================== +Building a Rasa Assistant in Docker +=================================== If you don't have a Rasa project yet, you can build one in Docker without having to install Rasa Open Source on your local machine. If you already have a model you're satisfied with, skip ahead to diff --git a/docs/user-guide/docker/deploying-in-docker.rst b/docs/user-guide/docker/deploying-in-docker.rst index 0e1fec92e0fd..fbad2f5b5f37 100644 --- a/docs/user-guide/docker/deploying-in-docker.rst +++ b/docs/user-guide/docker/deploying-in-docker.rst @@ -139,7 +139,7 @@ Deploying an Action Server Image ******************************** If you build an image that includes your action code and store it in a container registry, you can run it locally -or as part of your Rasa X or Rasa Enterprise deployment, without having to move code between servers. +or as part of your deployment, without having to move code between servers. In addition, you can add any additional dependencies of systems or Python libraries that are part of your action code but not included in the base ``rasa/rasa-sdk`` image. diff --git a/docs/user-guide/how-to-deploy.rst b/docs/user-guide/how-to-deploy.rst index 24f15bfeeaab..1caffbe873f1 100644 --- a/docs/user-guide/how-to-deploy.rst +++ b/docs/user-guide/how-to-deploy.rst @@ -34,30 +34,31 @@ The recommended way to deploy an assistant is using either the Docker Compose or Kubernetes/Openshift ~~~~~~~~~~~~~~~~~~~~ -Kubernetes/Openshift is the best option if you need a scalable architecture. It's straightforward to deploy if you use the helm charts we provide. However, you can also customize the Helm charts if you have specific requirements. +Kubernetes or Openshift is the best option if you need a scalable architecture. It's straightforward to deploy if you use the helm charts we provide. However, you can also customize the Helm charts if you have specific requirements. - - Default: Read the docs `here `__. - - Custom: Read the docs `here `__ and customize the `open source Helm charts `_. + - Default: Read the `Deploying in Openshift or Kubernetes `_ docs. + - Custom: Read the above, as well as the `Advanced Configuration `_ + documentation, and customize the `open source Helm charts `_ to your needs. Docker Compose ~~~~~~~~~~~~~~ - - Default: Watching this `video `__ or read the docs `here `__. - - Custom: Read the docs `here `__. + - Default: Watch the `Masterclass Video `_ on deploying Rasa X or read the `Docker-Compose Quick Install `_ docs. + - Custom: Read the docs `Docker-Compose Manual Install `_ documentation for full customization options. .. _rasa-only-deployment: -Rasa-Only Deployment with Docker Compose ----------------------------------------- +Alternative Deployment +---------------------- It is also possible to deploy a Rasa assistant using Docker-Compose without Rasa X. To do so, you can build your -Rasa Assistant :ref:`locally` or :ref:`in Docker`. Then you can -:ref:`deploy your model in Docker-Compose`. +Rasa Assistant locally or in Docker. Then you can deploy your model in Docker-Compose. .. toctree:: :titlesonly: :maxdepth: 1 + Building a Rasa Assistant Locally docker/building-in-docker docker/deploying-in-docker From aed2e347731bee040dd9a50ece2c4b2a095530c6 Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 16 Mar 2020 16:27:30 +0100 Subject: [PATCH 09/27] suggest one-line deployment --- ...er.rst => deploying-in-docker-compose.rst} | 0 docs/user-guide/how-to-deploy.rst | 53 +++++++++++++++---- 2 files changed, 42 insertions(+), 11 deletions(-) rename docs/user-guide/docker/{deploying-in-docker.rst => deploying-in-docker-compose.rst} (100%) diff --git a/docs/user-guide/docker/deploying-in-docker.rst b/docs/user-guide/docker/deploying-in-docker-compose.rst similarity index 100% rename from docs/user-guide/docker/deploying-in-docker.rst rename to docs/user-guide/docker/deploying-in-docker-compose.rst diff --git a/docs/user-guide/how-to-deploy.rst b/docs/user-guide/how-to-deploy.rst index 1caffbe873f1..434b9a439288 100644 --- a/docs/user-guide/how-to-deploy.rst +++ b/docs/user-guide/how-to-deploy.rst @@ -20,37 +20,68 @@ When to Deploy Your Assistant .. raw:: html - The best time to deploy your assistant and make it available to test users is once it can handle the most important happy paths or is what we call a minimum viable assistant. + The best time to deploy your assistant and make it available to test users is once it can handle the most + important happy paths or is what we call a minimum viable assistant. -The recommended deployment methods described below make it easy to share your assistant with test users via the `share your assistant feature in Rasa X `_. Then, when you’re ready to make your assistant available via one or more :ref:`messaging-and-voice-channels`, you can easily add them to your existing deployment set up. +The recommended deployment methods described below make it easy to share your assistant +with test users via the `share your assistant feature in +Rasa X `_. +Then, when you’re ready to make your assistant available via one or more :ref:`messaging-and-voice-channels`, +you can easily add them to your existing deployment set up. .. _recommended-deployment-methods: Recommended Deployment Methods ------------------------------ -The recommended way to deploy an assistant is using either the Docker Compose or Kubernetes/Openshift options we support. Both deploy Rasa X and your assistant. They are the easiest ways to deploy your assistant, allow you to use Rasa X to view conversations and turn them into training data, and are production-ready. +The recommended way to deploy an assistant is using either the One-Line Deployment or Kubernetes/Openshift +options we support. Both deploy Rasa X and your assistant. They are the easiest ways to deploy your assistant, +allow you to use Rasa X to view conversations and turn them into training data, and are production-ready. + +One-Line Deploy Script +~~~~~~~~~~~~~~~~~~~~~~ + +The one-line deployment script is the easiest way to deploy Rasa X and your assistant. It installs a Kubernetes +cluster on your machine with sensible defaults, getting you up and running in one command. + + - Default: Make sure you meet the `OS Requirements `_, + then run: + + .. copyable:: + + curl -s get-rasa-x.rasa.com | sudo bash + + - Custom: See `Customizing the Script `_ + in the `One-Line Deploy Script `_ docs. Kubernetes/Openshift ~~~~~~~~~~~~~~~~~~~~ -Kubernetes or Openshift is the best option if you need a scalable architecture. It's straightforward to deploy if you use the helm charts we provide. However, you can also customize the Helm charts if you have specific requirements. +For assistants that will receive a lot of user traffic, setting up a Kubernetes or Openshift deployment via +our helm charts is the best option. This provides a scalable architecture that is also straightforward to deploy. +However, you can also customize the Helm charts if you have specific requirements. - Default: Read the `Deploying in Openshift or Kubernetes `_ docs. - Custom: Read the above, as well as the `Advanced Configuration `_ documentation, and customize the `open source Helm charts `_ to your needs. -Docker Compose +.. _rasa-only-deployment: + +Alternative Deployment +---------------------- + +Docker-Compose ~~~~~~~~~~~~~~ +You can also run Rasa X in a Docker-Compose setup, without the cluster environment. We have a quick install script +for doing so, as well as manual instructions for any custom setups. + - Default: Watch the `Masterclass Video `_ on deploying Rasa X or read the `Docker-Compose Quick Install `_ docs. - Custom: Read the docs `Docker-Compose Manual Install `_ documentation for full customization options. - -.. _rasa-only-deployment: - -Alternative Deployment ----------------------- +Rasa-Only Deployment +~~~~~~~~~~~~~~~~~~~~ It is also possible to deploy a Rasa assistant using Docker-Compose without Rasa X. To do so, you can build your Rasa Assistant locally or in Docker. Then you can deploy your model in Docker-Compose. @@ -61,4 +92,4 @@ Rasa Assistant locally or in Docker. Then you can deploy your model in Docker-Co Building a Rasa Assistant Locally docker/building-in-docker - docker/deploying-in-docker + docker/deploying-in-docker-compose From 6c867a19aa6d5dfe5b120e49f3697288e5d715ea Mon Sep 17 00:00:00 2001 From: Ella Date: Tue, 17 Mar 2020 14:02:47 +0100 Subject: [PATCH 10/27] edits to deploy in docker-compose page --- .../connectors/custom-connectors.rst | 2 +- docs/user-guide/docker/building-in-docker.rst | 6 +- .../docker/deploying-in-docker-compose.rst | 302 ++++++++++-------- docs/user-guide/how-to-deploy.rst | 19 +- 4 files changed, 174 insertions(+), 155 deletions(-) diff --git a/docs/user-guide/connectors/custom-connectors.rst b/docs/user-guide/connectors/custom-connectors.rst index a45c73b5a34f..2c9720795644 100644 --- a/docs/user-guide/connectors/custom-connectors.rst +++ b/docs/user-guide/connectors/custom-connectors.rst @@ -27,7 +27,7 @@ To send a message, you would run a command like: .. code-block:: bash - curl -XPOST http://localhost:5000/webhooks/myio/webhook \ + curl -XPOST http://localhost:5005/webhooks/myio/webhook \ -d '{"sender": "user1", "message": "hello"}' \ -H "Content-type: application/json" diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index e2d5c6b8ab84..004348ac2ee0 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -1,11 +1,13 @@ +:desc: Learn how to build a Rasa assistant in Docker. + .. _building-in-docker: Building a Rasa Assistant in Docker =================================== If you don't have a Rasa project yet, you can build one in Docker without having to install Rasa Open Source -on your local machine. If you already have a model you're satisfied with, skip ahead to -:ref:`deploying-rasa-in-docker-compose` to deploy your model. +on your local machine. If you already have a model you're satisfied with, go to +:ref:`how-to-deploy` to learn how to deploy your model. .. contents:: :local: diff --git a/docs/user-guide/docker/deploying-in-docker-compose.rst b/docs/user-guide/docker/deploying-in-docker-compose.rst index fbad2f5b5f37..9524e8f170e4 100644 --- a/docs/user-guide/docker/deploying-in-docker-compose.rst +++ b/docs/user-guide/docker/deploying-in-docker-compose.rst @@ -1,11 +1,16 @@ +:desc: Use Docker Compose to deploy a Rasa assistant alongside the action server. + .. _deploying-rasa-in-docker-compose: -Deploying a Rasa Assistant in Docker-Compose -============================================ +Deploying a Rasa-Only Assistant in Docker Compose +================================================= + +If you would like to deploy a Rasa assistant without Rasa X, you can do so by deploying it in Docker Compose. +To deploy Rasa X and your assistant together, see the :ref:`recommended-deployment-methods`. .. contents:: :local: - :depth: 2 + :depth: 1 Installing Docker @@ -24,37 +29,58 @@ versions of Docker and Docker Compose. If the command doesn't work, you'll have install Docker. See `Docker Installation `_ for details. -.. _running-the-rasa-server: -Running the Rasa Server -~~~~~~~~~~~~~~~~~~~~~~~ +Configuring Channels +~~~~~~~~~~~~~~~~~~~~ To run your AI assistant in production, configure your required -:ref:`messaging-and-voice-channels` in ``credentials.yml``. If this file does not -exist, create it using: +:ref:`messaging-and-voice-channels` in ``credentials.yml``. For example, to add a +REST channel, uncomment this section in the ``credentials.yml``: + + .. code-block:: yaml + + rest: + # you don't need to provide anything here - this channel doesn't + # require any credentials -.. code-block:: bash +The REST channel will open your bot up to incoming requests at the ``/webhooks/rest/webhook`` endpoint. - touch credentials.yml +.. _running-a-rasa-server: -Then edit it according to your connected channels. -After, run the trained model with: +Running a Rasa Server +~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: bash +The Rasa server can be run alone in Docker: - docker run \ - -v $(pwd)/models:/app/models \ - rasa/rasa:latest-full \ - run + .. code-block:: bash + + docker run \ + -v $(pwd):/app \ + -p 5005:5005 \ + rasa/rasa:latest-full \ + run Command Description: - - ``-v $(pwd)/models:/app/models``: Mounts the directory with the trained Rasa model - in the container + - ``-v $(pwd):/app``: Mounts the working directory into the Rasa container for + access to the trained models as well as the credentials and endpoints configurations + - ``-p 5005:5005``: Map the port that runs Rasa to the host machine so that it is + accessible to receive messages - ``rasa/rasa:latest-full``: Use the Rasa image with the tag ``latest-full`` - ``run``: Executes the ``rasa run`` command. For more information see :ref:`command-line-interface`. +Then you should be able to send messages to your bot with this curl request, for example: + + .. code-block:: bash + + curl -XPOST http://localhost:5005/webhooks/rest/webhook \ + -H "Content-type: application/json" \ + -d '{"sender": "test", "message": "hello"}' + +If your bot has custom actions, you'll have to deploy an action server image and use Docker Compose to +run both services. + Using Docker Compose to Run Multiple Services ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -62,7 +88,7 @@ Using Docker Compose to Run Multiple Services To run Rasa together with other services, such as a server for custom actions, it is recommend to use `Docker Compose `_. Docker Compose provides an easy way to run multiple containers together without -having to run multiple commands. +having to run multiple commands or configure networks. .. contents:: :local: @@ -70,73 +96,68 @@ having to run multiple commands. Start by creating a file called ``docker-compose.yml``: -.. code-block:: bash + .. code-block:: bash - touch docker-compose.yml + touch docker-compose.yml Add the following content to the file: -.. code-block:: yaml - - version: '3.0' - services: - rasa: - image: rasa/rasa:latest-full - ports: - - 5005:5005 - volumes: - - ./:/app - command: - - run + .. code-block:: yaml + version: '3.0' + services: + rasa: + image: rasa/rasa:latest-full + ports: + - 5005:5005 + volumes: + - ./:/app + command: + - run The file starts with the version of the Docker Compose specification that you want to use. -Each container is declared as a ``service`` within the docker-compose file. -The first service is the ``rasa`` service. - -The command is similar to the ``docker run`` command. -The ``ports`` part defines a port mapping between the container and your host -system. In this case it makes ``5005`` of the ``rasa`` service available on -port ``5005`` of your host. -This is the port of the :ref:`REST Channel ` interface of Rasa. - -.. note:: - - Since Docker Compose starts a set of Docker containers, it is no longer - possible to connect to the command line of a single container after executing the - ``run`` command. - +Each container is declared as a ``service`` within the ``docker-compose.yml``. +The first service is the ``rasa`` service. The configuration here is the equivalent to the +``docker run`` command shown in :ref:`running-a-rasa-server`. To add the action server, add the image of your action server code. To learn how to deploy an action server image, see :ref:`building-an-action-server-image`. -.. code-block:: yaml - :emphasize-lines: 11-14 - - version: '3.0' - services: - rasa: - image: rasa/rasa:latest-full - ports: - - 5005:5005 - volumes: - - ./:/app - command: - - run - app: - image: + .. code-block:: yaml + :emphasize-lines: 11-12 + + version: '3.0' + services: + rasa: + image: rasa/rasa:latest-full + ports: + - 5005:5005 + volumes: + - ./:/app + command: + - run + app: + image: To run the services configured in your ``docker-compose.yml`` execute: -.. code-block:: bash + .. code-block:: bash - docker-compose up + docker-compose up + +You should then be able to interact with your bot via requests to port 5005: + + .. code-block:: bash + + curl -XPOST http://localhost:5005/webhooks/rest/webhook \ + -H "Content-type: application/json" \ + -d '{"sender": "test", "message": "hello"}' .. _building-an-action-server-image: -Deploying an Action Server Image -******************************** +Building an Action Server Image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you build an image that includes your action code and store it in a container registry, you can run it locally or as part of your deployment, without having to move code between servers. @@ -155,73 +176,72 @@ To create your image, first create a list of your custom actions requirements in ``actions/requirements-actions.txt``. Then create a file named ``Dockerfile`` in your project directory, in which you'll extend the official SDK image, copy over your code, and add any custom dependencies. For example: -.. code-block:: docker + .. code-block:: docker - # Extend the official Rasa SDK image - FROM rasa/rasa-sdk:latest + # Extend the official Rasa SDK image + FROM rasa/rasa-sdk:latest - # Use subdirectory as working directory - WORKDIR /app + # Use subdirectory as working directory + WORKDIR /app - # Copy any additional custom requirements - COPY actions/requirements-actions.txt ./ + # Copy any additional custom requirements + COPY actions/requirements-actions.txt ./ - # Change back to root user to install dependencies - USER root + # Change back to root user to install dependencies + USER root - # Install extra requirements for actions code - RUN pip install -r requirements-actions.txt + # Install extra requirements for actions code + RUN pip install -r requirements-actions.txt - # Copy actions code to working directory - COPY ./actions /app/actions - - # By best practices, don't run the code with root user - USER 1001 + # Copy actions code to working directory + COPY ./actions /app/actions + # By best practices, don't run the code with root user + USER 1001 You can then build the image via the following command: -.. code-block:: bash + .. code-block:: bash - docker build . -t /: + docker build . -t /: The ```` should reference how this image will be different from others. For example, you could version or date your tags, as well as create different tags that have different code for production and development servers. You should create a new tag any time you update your code and want to re-deploy it. -If you are using docker-compose locally, you can use this image directly in your +If you are using Docker Compose locally, you can use this image directly in your ``docker-compose.yml``: -.. code-block:: yaml + .. code-block:: yaml - version: '3.0' - services: - app: - image: /: + version: '3.0' + services: + app: + image: /: If you're building this image to make it available from another server, for example a Rasa X or Rasa Enterprise deployment, you should push the image to a cloud repository. You can push the image to DockerHub via: -.. code-block:: bash + .. code-block:: bash - docker login --username --password - docker push /: + docker login --username --password + docker push /: To authenticate and push images to a different container registry, please refer to the documentation of your chosen container registry. Then, reference the new image tag in your ``docker-compose.override.yml``: -.. code-block:: yaml + .. code-block:: yaml - version: '3.0' - services: - app: - image: /: + version: '3.0' + services: + app: + image: /: Adding a Custom Tracker Store -***************************** +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, all conversations are saved in memory. This means that all conversations are lost as soon as you restart the Rasa server. @@ -235,78 +255,78 @@ If you want to persist your conversations, you can use a different Using PostgreSQL as Tracker Store ################################# -Start by adding PostgreSQL to your docker-compose file: +Start by adding PostgreSQL to your ``docker-compose.yml``: -.. code-block:: yaml + .. code-block:: yaml - postgres: - image: postgres:latest + postgres: + image: postgres:latest Then add PostgreSQL to the ``tracker_store`` section of your endpoint configuration ``config/endpoints.yml``: -.. code-block:: yaml + .. code-block:: yaml - tracker_store: - type: sql - dialect: "postgresql" - url: postgres - db: rasa + tracker_store: + type: sql + dialect: "postgresql" + url: postgres + db: rasa Using MongoDB as Tracker Store ############################## -Start by adding MongoDB to your docker-compose file. The following example +Start by adding MongoDB to your ``docker-compose.yml``. The following example adds the MongoDB as well as a UI (you can skip this), which will be available at ``localhost:8081``. Username and password for the MongoDB instance are specified as ``rasa`` and ``example``. -.. code-block:: yaml - - mongo: - image: mongo - environment: - MONGO_INITDB_ROOT_USERNAME: rasa - MONGO_INITDB_ROOT_PASSWORD: example - mongo-express: - image: mongo-express - ports: - - 8081:8081 - environment: - ME_CONFIG_MONGODB_ADMINUSERNAME: rasa - ME_CONFIG_MONGODB_ADMINPASSWORD: example + .. code-block:: yaml + + mongo: + image: mongo + environment: + MONGO_INITDB_ROOT_USERNAME: rasa + MONGO_INITDB_ROOT_PASSWORD: example + mongo-express: + image: mongo-express + ports: + - 8081:8081 + environment: + ME_CONFIG_MONGODB_ADMINUSERNAME: rasa + ME_CONFIG_MONGODB_ADMINPASSWORD: example Then add the MongoDB to the ``tracker_store`` section of your endpoints configuration ``endpoints.yml``: -.. code-block:: yaml + .. code-block:: yaml - tracker_store: - type: mongod - url: mongodb://mongo:27017 - username: rasa - password: example + tracker_store: + type: mongod + url: mongodb://mongo:27017 + username: rasa + password: example Then start all components with ``docker-compose up``. Using Redis as Tracker Store -############################## +############################ -Start by adding Redis to your docker-compose file: +Start by adding Redis to your ``docker-compose.yml``: -.. code-block:: yaml + .. code-block:: yaml - redis: - image: redis:latest + redis: + image: redis:latest Then add Redis to the ``tracker_store`` section of your endpoint configuration ``endpoints.yml``: -.. code-block:: yaml + .. code-block:: yaml - tracker_store: - type: redis - url: redis + tracker_store: + type: redis + url: redis Using a Custom Tracker Store Implementation ########################################### diff --git a/docs/user-guide/how-to-deploy.rst b/docs/user-guide/how-to-deploy.rst index 434b9a439288..1fdb1a19b019 100644 --- a/docs/user-guide/how-to-deploy.rst +++ b/docs/user-guide/how-to-deploy.rst @@ -18,11 +18,8 @@ It will allow you to make your assistant available to users and set you up with When to Deploy Your Assistant ----------------------------- -.. raw:: html - - The best time to deploy your assistant and make it available to test users is once it can handle the most - important happy paths or is what we call a minimum viable assistant. +The best time to deploy your assistant and make it available to test users is once it can handle the most +important happy paths or is what we call a `minimum viable assistant `_. The recommended deployment methods described below make it easy to share your assistant with test users via the `share your assistant feature in @@ -71,20 +68,20 @@ However, you can also customize the Helm charts if you have specific requirement Alternative Deployment ---------------------- -Docker-Compose +Docker Compose ~~~~~~~~~~~~~~ -You can also run Rasa X in a Docker-Compose setup, without the cluster environment. We have a quick install script +You can also run Rasa X in a Docker Compose setup, without the cluster environment. We have a quick install script for doing so, as well as manual instructions for any custom setups. - - Default: Watch the `Masterclass Video `_ on deploying Rasa X or read the `Docker-Compose Quick Install `_ docs. - - Custom: Read the docs `Docker-Compose Manual Install `_ documentation for full customization options. + - Default: Watch the `Masterclass Video `_ on deploying Rasa X or read the `Docker Compose Quick Install `_ docs. + - Custom: Read the docs `Docker Compose Manual Install `_ documentation for full customization options. Rasa-Only Deployment ~~~~~~~~~~~~~~~~~~~~ -It is also possible to deploy a Rasa assistant using Docker-Compose without Rasa X. To do so, you can build your -Rasa Assistant locally or in Docker. Then you can deploy your model in Docker-Compose. +It is also possible to deploy a Rasa assistant using Docker Compose without Rasa X. To do so, you can build your +Rasa Assistant locally or in Docker. Then you can deploy your model in Docker Compose. .. toctree:: :titlesonly: From 6b463a57f87e9d3016f8b3478bd66622a1847de3 Mon Sep 17 00:00:00 2001 From: Ella Date: Tue, 17 Mar 2020 15:47:09 +0100 Subject: [PATCH 11/27] small improvements to docs --- docs/user-guide/docker/building-in-docker.rst | 126 +++++++++--------- .../docker/deploying-in-docker-compose.rst | 11 +- 2 files changed, 73 insertions(+), 64 deletions(-) diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index 004348ac2ee0..ea09fa7ae499 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -35,9 +35,9 @@ Just like in the :ref:`tutorial `, you'll use the ``rasa init`` c The only difference is that you'll be running Rasa inside a Docker container, using the image ``rasa/rasa``. To initialize your project, run: -.. code-block:: bash + .. code-block:: bash - docker run -v $(pwd):/app rasa/rasa init --no-prompt + docker run -v $(pwd):/app rasa/rasa init --no-prompt What does this command mean? @@ -56,9 +56,9 @@ Running this command will produce a lot of output. What happens is: To check that the command completed correctly, look at the contents of your working directory: -.. code-block:: bash + .. code-block:: bash - ls -1 + ls -1 The initial project files should all be there, as well as a ``models`` directory that contains your trained model. @@ -77,9 +77,9 @@ Talking to Your Assistant To talk to your newly-trained assistant, run this command: -.. code-block:: bash + .. code-block:: bash - docker run -it -v $(pwd):/app rasa/rasa shell + docker run -it -v $(pwd):/app rasa/rasa shell This will start a shell where you can chat to your assistant. Note that this command includes the flags ``-it``, which means that you are running @@ -126,15 +126,15 @@ Edit the ``config.yml`` file to use the pipeline you want, and place your NLU and Core data into the ``data/`` directory. Now you can train your Rasa model by running: -.. code-block:: bash + .. code-block:: bash - docker run \ - -v $(pwd):/app \ - rasa/rasa:latest-full \ - train \ - --domain domain.yml \ - --data data \ - --out models + docker run \ + -v $(pwd):/app \ + rasa/rasa:latest-full \ + train \ + --domain domain.yml \ + --data data \ + --out models Here's what's happening in that command: @@ -165,81 +165,81 @@ the user a joke to cheer them up. Start by creating the custom actions in a directory ``actions`` in your working directory: -.. code-block:: bash + .. code-block:: bash - mkdir actions - mv actions.py actions/actions.py - # Rasa SDK expects a python module. - # Therefore, make sure that you have this file in the directory. - touch actions/__init__.py + mkdir actions + mv actions.py actions/actions.py + # Rasa SDK expects a python module. + # Therefore, make sure that you have this file in the directory. + touch actions/__init__.py -Then build a custom action using the Rasa SDK by editing ``actions/actions.py``, e.g.: +Then build a custom action using the Rasa SDK by editing ``actions/actions.py``, for example: -.. code-block:: python + .. code-block:: python - import requests - import json - from rasa_sdk import Action + import requests + import json + from rasa_sdk import Action - class ActionJoke(Action): - def name(self): - return "action_joke" + class ActionJoke(Action): + def name(self): + return "action_joke" - def run(self, dispatcher, tracker, domain): - request = requests.get('http://api.icndb.com/jokes/random').json() # make an api call - joke = request['value']['joke'] # extract a joke from returned json response - dispatcher.utter_message(text=joke) # send the message back to the user - return [] + def run(self, dispatcher, tracker, domain): + request = requests.get('http://api.icndb.com/jokes/random').json() # make an api call + joke = request['value']['joke'] # extract a joke from returned json response + dispatcher.utter_message(text=joke) # send the message back to the user + return [] -To tell your bot to use this new action, replace ``utter_cheer_up`` in -``data/stories.md`` with the custom action ``action_joke``. +In ``data/stories.md``, replace ``utter_cheer_up`` in with the custom action ``action_joke`` +tell your bot to use this new action. In ``domain.yml``, add a section for custom actions, including your new action: -.. code-block:: yaml + .. code-block:: yaml - actions: - - action_joke + actions: + - action_joke To instruct the Rasa server to use the action server, you have to tell Rasa its location. Add this to your ``endpoints.yml``: -.. code-block:: yaml + .. code-block:: yaml - action_endpoint: - url: http://app:5055/webhook + action_endpoint: + url: http://localhost:5055/webhook After updating your domain and stories, you have to retrain your model: -.. code-block:: bash + .. code-block:: bash - docker run \ - -v $(pwd):/app \ - rasa/rasa:latest-full \ - train + docker run \ + -v $(pwd):/app \ + rasa/rasa:latest-full \ + train To spin up the action server together with the Rasa instance, add a service ``app`` to the ``docker-compose.yml``: -.. code-block:: yaml - :emphasize-lines: 11-14 - - version: '3.0' - services: - rasa: - image: rasa/rasa:latest-full - ports: - - 5005:5005 - volumes: - - ./:/app - command: - - run - app: - image: rasa/rasa-sdk:latest - volumes: - - ./actions:/app/actions + .. code-block:: yaml + :emphasize-lines: 11-14 + + version: '3.0' + services: + rasa: + image: rasa/rasa:latest-full + ports: + - 5005:5005 + volumes: + - ./:/app + command: + - run + app: + image: rasa/rasa-sdk:latest + volumes: + - ./actions:/app/actions This pulls the image for the Rasa SDK which includes the action server, mounts your custom actions into it, and starts the server. diff --git a/docs/user-guide/docker/deploying-in-docker-compose.rst b/docs/user-guide/docker/deploying-in-docker-compose.rst index 9524e8f170e4..987189fe655f 100644 --- a/docs/user-guide/docker/deploying-in-docker-compose.rst +++ b/docs/user-guide/docker/deploying-in-docker-compose.rst @@ -125,7 +125,7 @@ To add the action server, add the image of your action server code. To learn how an action server image, see :ref:`building-an-action-server-image`. .. code-block:: yaml - :emphasize-lines: 11-12 + :emphasize-lines: 11-13 version: '3.0' services: @@ -139,6 +139,15 @@ an action server image, see :ref:`building-an-action-server-image`. - run app: image: + expose: 5055 + +The ``expose: 5005`` is what allows the ``rasa`` service to reach the ``app`` service on that port. +To instruct the ``rasa`` service to send its action requests to that endpoint, add it to your ``endpoints.yml``: + + .. code-block:: yaml + + action_endpoint: + url: http://app:5055/webhook To run the services configured in your ``docker-compose.yml`` execute: From 486d64ab242dde9584e2ed7d86125fb425f35f54 Mon Sep 17 00:00:00 2001 From: Ella Date: Tue, 17 Mar 2020 17:13:38 +0100 Subject: [PATCH 12/27] no more docker compose --- docs/user-guide/docker/building-in-docker.rst | 99 ++++++++++++------- 1 file changed, 62 insertions(+), 37 deletions(-) diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index ea09fa7ae499..245861af8638 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -19,13 +19,11 @@ If you're not sure if you have Docker installed, you can check by running: .. code-block:: bash - docker -v && docker-compose -v + docker -v # Docker version 18.09.2, build 6247962 - # docker-compose version 1.23.2, build 1110ad01 If Docker is installed on your machine, the output should show you your installed -versions of Docker and Docker Compose. If the command doesn't work, you'll have to -install Docker. +versions of Docker. If the command doesn't work, you'll have to install Docker. See `Docker Installation `_ for details. Setting up your Rasa Project @@ -66,10 +64,9 @@ The initial project files should all be there, as well as a ``models`` directory .. note:: By default Docker runs containers as user ``1001``. Hence, all files created by - these containers will be owned by this user. See the `documentation of docker + these containers will be owned by this user. See the `Docker documentation `_ - and `docker-compose `_ if you want to - run the containers as a different user. + if you want to run the containers as a different user. Talking to Your Assistant ************************* @@ -156,6 +153,7 @@ You can also leave these out since we are passing the default values. that your module is in the Python module search path by setting the environment variable ``PYTHONPATH=$PYTHONPATH:``. + Adding Custom Actions ********************* @@ -203,14 +201,6 @@ In ``domain.yml``, add a section for custom actions, including your new action: actions: - action_joke -To instruct the Rasa server to use the action server, you have to tell Rasa its location. -Add this to your ``endpoints.yml``: - - .. code-block:: yaml - - action_endpoint: - url: http://localhost:5055/webhook - After updating your domain and stories, you have to retrain your model: .. code-block:: bash @@ -220,32 +210,67 @@ After updating your domain and stories, you have to retrain your model: rasa/rasa:latest-full \ train -To spin up the action server together with the Rasa instance, add a service -``app`` to the ``docker-compose.yml``: +Your actions will run on a separate server from your Rasa server. First create a network to connect the two containers: + + .. code-block:: bash + + docker network create my-project + +You can then run the actions with the following command: + + .. code-block:: bash + + docker run -d \ + -v $(pwd)/actions:/app/actions \ + --net my-project \ + --name action-server + rasa/rasa-sdk:latest + + +Here's what's happening in that command: + + - ``-d``: Runs the container in detached mode so that you can run the rasa container in the same + window. Run ``docker ps`` at any time to see all of your currently running containers + - ``-v $(pwd):/app``: Mounts your project directory into the Docker + container so that the action server can run the code in the ``actions`` folder + - ``net my-project``: Run the server on a specific network so that the rasa container can find it + - ``--name action-server``: Gives the server a specific name for the rasa server to reference + - ``rasa/rasa-sdk:latest``: Uses the Rasa SDK image with the tag ``latest`` - .. code-block:: yaml - :emphasize-lines: 11-14 - - version: '3.0' - services: - rasa: - image: rasa/rasa:latest-full - ports: - - 5005:5005 - volumes: - - ./:/app - command: - - run - app: - image: rasa/rasa-sdk:latest - volumes: - - ./actions:/app/actions This pulls the image for the Rasa SDK which includes the action server, -mounts your custom actions into it, and starts the server. +mounts your custom actions into it, and starts the server. Because it's running in detached mode, +if you want to stop the container, do it with ``docker stop action-server``. + +To instruct the Rasa server to use the action server, you have to tell Rasa its location. +Add this endpoint to your ``endpoints.yml``, referencing the ``--name`` you gave the server: + + .. code-block:: yaml + + action_endpoint: + url: "http://action-server:5055/webhook" + +Now you can talk to your bot again via the ``shell`` command: + + .. code-block:: bash -Run ``docker-compose up`` to start the action server together with the Rasa server. + docker run -it -v $(pwd):/app -p 5005:5005 --net my-project rasa/rasa shell + +.. note:: + + If you stop and restart the ``action-server`` container, you might see an error like this: + + .. code-block:: none + + docker: Error response from daemon: Conflict. The container name "/action-server" is + already in use by container "f7ffc625e81ad4ad54cf8704e6ad85123c71781ca0a8e4b862f41c5796c33530". + You have to remove (or rename) that container to be able to reuse that name. + + If that happens, it means you have a (stopped) container with the name already. You can remove it via: + + .. code-block:: bash + docker rm action-server Deploying your Model ******************** @@ -253,4 +278,4 @@ Deploying your Model Work on your bot until you have a minimum viable assistant that can handle your happy paths. After that, you'll want to deploy your model to get feedback from real test users. To do so, you can deploy the model you created with Rasa X via one of our :ref:`recommended deployment methods`. -Or, you can do a :ref:`Rasa-only deployment in Docker-Compose`. \ No newline at end of file +Or, you can do a :ref:`Rasa-only deployment in Docker Compose`. From adb741c0f7e45bbbbae10e0ea1592766673e69b2 Mon Sep 17 00:00:00 2001 From: Ella Date: Tue, 17 Mar 2020 17:15:33 +0100 Subject: [PATCH 13/27] fix errors --- docs/user-guide/docker/building-in-docker.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index 245861af8638..28a17e026052 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -6,8 +6,8 @@ Building a Rasa Assistant in Docker =================================== If you don't have a Rasa project yet, you can build one in Docker without having to install Rasa Open Source -on your local machine. If you already have a model you're satisfied with, go to -:ref:`how-to-deploy` to learn how to deploy your model. +on your local machine. If you already have a model you're satisfied with, see +:ref:`deploying-your-rasa-assistant` to learn how to deploy your model. .. contents:: :local: From 234fcef9ad9a73e1a92ed0c56c482773a6098530 Mon Sep 17 00:00:00 2001 From: Ella Date: Thu, 19 Mar 2020 15:24:43 +0100 Subject: [PATCH 14/27] fix some review comments --- docs/user-guide/docker/building-in-docker.rst | 19 +++-- .../docker/deploying-in-docker-compose.rst | 70 +++++-------------- 2 files changed, 28 insertions(+), 61 deletions(-) diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index 28a17e026052..1d5764babc3d 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -63,8 +63,9 @@ The initial project files should all be there, as well as a ``models`` directory .. note:: - By default Docker runs containers as user ``1001``. Hence, all files created by - these containers will be owned by this user. See the `Docker documentation + If you run into permission errors, it may be because the ``rasa/rasa`` images + run as user ``1001`` as a best practice, to avoid giving the container ``root`` permissions. + Hence, all files created by these containers will be owned by user ``1001``. See the `Docker documentation `_ if you want to run the containers as a different user. @@ -73,7 +74,6 @@ Talking to Your Assistant To talk to your newly-trained assistant, run this command: - .. code-block:: bash docker run -it -v $(pwd):/app rasa/rasa shell @@ -229,8 +229,7 @@ You can then run the actions with the following command: Here's what's happening in that command: - - ``-d``: Runs the container in detached mode so that you can run the rasa container in the same - window. Run ``docker ps`` at any time to see all of your currently running containers + - ``-d``: Runs the container in detached mode so that you can run the rasa container in the same window. - ``-v $(pwd):/app``: Mounts your project directory into the Docker container so that the action server can run the code in the ``actions`` folder - ``net my-project``: Run the server on a specific network so that the rasa container can find it @@ -238,9 +237,9 @@ Here's what's happening in that command: - ``rasa/rasa-sdk:latest``: Uses the Rasa SDK image with the tag ``latest`` -This pulls the image for the Rasa SDK which includes the action server, -mounts your custom actions into it, and starts the server. Because it's running in detached mode, -if you want to stop the container, do it with ``docker stop action-server``. +Because the action server is running in detached mode, if you want to stop the container, +do it with ``docker stop action-server``. You can also run ``docker ps`` at any time to see all +of your currently running containers. To instruct the Rasa server to use the action server, you have to tell Rasa its location. Add this endpoint to your ``endpoints.yml``, referencing the ``--name`` you gave the server: @@ -272,8 +271,8 @@ Now you can talk to your bot again via the ``shell`` command: docker rm action-server -Deploying your Model -******************** +Deploying your Assistant +************************ Work on your bot until you have a minimum viable assistant that can handle your happy paths. After that, you'll want to deploy your model to get feedback from real test users. To do so, you can deploy the diff --git a/docs/user-guide/docker/deploying-in-docker-compose.rst b/docs/user-guide/docker/deploying-in-docker-compose.rst index 987189fe655f..7fbb8a19fe6e 100644 --- a/docs/user-guide/docker/deploying-in-docker-compose.rst +++ b/docs/user-guide/docker/deploying-in-docker-compose.rst @@ -1,11 +1,11 @@ -:desc: Use Docker Compose to deploy a Rasa assistant alongside the action server. +:desc: Use Docker Compose to deploy a Rasa Open Source assistant .. _deploying-rasa-in-docker-compose: -Deploying a Rasa-Only Assistant in Docker Compose -================================================= +Deploying a Rasa Open Source Assistant in Docker Compose +======================================================== -If you would like to deploy a Rasa assistant without Rasa X, you can do so by deploying it in Docker Compose. +If you would like to deploy your assistant without Rasa X, you can do so by deploying it in Docker Compose. To deploy Rasa X and your assistant together, see the :ref:`recommended-deployment-methods`. .. contents:: @@ -30,10 +30,12 @@ install Docker. See `Docker Installation `_ for details. +.. _docker-compose-configuring-channels: + Configuring Channels ~~~~~~~~~~~~~~~~~~~~ -To run your AI assistant in production, configure your required +To run your AI assistant in production, don't forget to configure your required :ref:`messaging-and-voice-channels` in ``credentials.yml``. For example, to add a REST channel, uncomment this section in the ``credentials.yml``: @@ -45,50 +47,13 @@ REST channel, uncomment this section in the ``credentials.yml``: The REST channel will open your bot up to incoming requests at the ``/webhooks/rest/webhook`` endpoint. -.. _running-a-rasa-server: - -Running a Rasa Server -~~~~~~~~~~~~~~~~~~~~~ - -The Rasa server can be run alone in Docker: - - .. code-block:: bash - - docker run \ - -v $(pwd):/app \ - -p 5005:5005 \ - rasa/rasa:latest-full \ - run - -Command Description: - - - ``-v $(pwd):/app``: Mounts the working directory into the Rasa container for - access to the trained models as well as the credentials and endpoints configurations - - ``-p 5005:5005``: Map the port that runs Rasa to the host machine so that it is - accessible to receive messages - - ``rasa/rasa:latest-full``: Use the Rasa image with the tag ``latest-full`` - - ``run``: Executes the ``rasa run`` command. For more information see - :ref:`command-line-interface`. - -Then you should be able to send messages to your bot with this curl request, for example: - - .. code-block:: bash - - curl -XPOST http://localhost:5005/webhooks/rest/webhook \ - -H "Content-type: application/json" \ - -d '{"sender": "test", "message": "hello"}' - -If your bot has custom actions, you'll have to deploy an action server image and use Docker Compose to -run both services. - Using Docker Compose to Run Multiple Services ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To run Rasa together with other services, such as a server for custom actions, it is -recommend to use `Docker Compose `_. Docker Compose provides an easy way to run multiple containers together without -having to run multiple commands or configure networks. +having to run multiple commands or configure networks. This is essential when you +want to deploy an assistant that also has an action server. .. contents:: :local: @@ -118,8 +83,7 @@ Add the following content to the file: The file starts with the version of the Docker Compose specification that you want to use. Each container is declared as a ``service`` within the ``docker-compose.yml``. -The first service is the ``rasa`` service. The configuration here is the equivalent to the -``docker run`` command shown in :ref:`running-a-rasa-server`. +The first service is the ``rasa`` service, which runs your Rasa server. To add the action server, add the image of your action server code. To learn how to deploy an action server image, see :ref:`building-an-action-server-image`. @@ -155,7 +119,8 @@ To run the services configured in your ``docker-compose.yml`` execute: docker-compose up -You should then be able to interact with your bot via requests to port 5005: +You should then be able to interact with your bot via requests to port 5005, on the webhook endpoint that +corresponds to a :ref:`configured channel `: .. code-block:: bash @@ -181,9 +146,12 @@ a different Docker registry, such as `Google Container Registry `_, or `Azure Container Registry `_. -To create your image, first create a list of your custom actions requirements in a file, -``actions/requirements-actions.txt``. Then create a file named ``Dockerfile`` in your project directory, -in which you'll extend the official SDK image, copy over your code, and add any custom dependencies. For example: +To create your image: + - If your actions have any extra dependencies, create a list of them in a file, + ``actions/requirements-actions.txt``. + - Create a file named ``Dockerfile`` in your project directory, + in which you'll extend the official SDK image, copy over your code, and add any custom dependencies (if necessary). + For example: .. code-block:: docker @@ -199,7 +167,7 @@ in which you'll extend the official SDK image, copy over your code, and add any # Change back to root user to install dependencies USER root - # Install extra requirements for actions code + # Install extra requirements for actions code, if necessary (otherwise comment this out) RUN pip install -r requirements-actions.txt # Copy actions code to working directory From 6483abc6678fe03124dad3e2ed2db0643a0b697b Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 23 Mar 2020 10:52:16 +0100 Subject: [PATCH 15/27] more review comments --- docs/user-guide/docker/building-in-docker.rst | 18 ++++++++++-------- docs/user-guide/how-to-deploy.rst | 10 +++++----- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index 1d5764babc3d..40c5ca70a6ee 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -116,8 +116,8 @@ Alternatively, you can use the ``-full`` tag, which includes all pipeline depend .. _model_training_docker: -Training a Custom Rasa Model with Docker -######################################## +Training a Model +################ Edit the ``config.yml`` file to use the pipeline you want, and place your NLU and Core data into the ``data/`` directory. @@ -145,13 +145,15 @@ In this case, we've also passed values for the location of the domain file, trai data, and the models output directory to show how these can be customized. You can also leave these out since we are passing the default values. -.. note:: - If you are using a custom NLU component or policy, you have to add the module file to your - Docker container. You can do this by either mounting the file or by including it in your - own custom image (e.g. if the custom component or policy has extra dependencies). Make sure - that your module is in the Python module search path by setting the - environment variable ``PYTHONPATH=$PYTHONPATH:``. +Adding Custom Components +************************ + +If you are using a custom NLU component or policy ot your ``config.yml``, you have to add the module file to your +Docker container. You can do this by either mounting the file or by including it in your +own custom image (e.g. if the custom component or policy has extra dependencies). Make sure +that your module is in the Python module search path by setting the +environment variable ``PYTHONPATH=$PYTHONPATH:``. Adding Custom Actions diff --git a/docs/user-guide/how-to-deploy.rst b/docs/user-guide/how-to-deploy.rst index 1fdb1a19b019..7a250c537f9e 100644 --- a/docs/user-guide/how-to-deploy.rst +++ b/docs/user-guide/how-to-deploy.rst @@ -65,8 +65,8 @@ However, you can also customize the Helm charts if you have specific requirement .. _rasa-only-deployment: -Alternative Deployment ----------------------- +Alternative Deployment Methods +------------------------------ Docker Compose ~~~~~~~~~~~~~~ @@ -77,10 +77,10 @@ for doing so, as well as manual instructions for any custom setups. - Default: Watch the `Masterclass Video `_ on deploying Rasa X or read the `Docker Compose Quick Install `_ docs. - Custom: Read the docs `Docker Compose Manual Install `_ documentation for full customization options. -Rasa-Only Deployment -~~~~~~~~~~~~~~~~~~~~ +Rasa Open Source Only Deployment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -It is also possible to deploy a Rasa assistant using Docker Compose without Rasa X. To do so, you can build your +It is also possible to deploy a Rasa assistant without Rasa X using Docker Compose. To do so, you can build your Rasa Assistant locally or in Docker. Then you can deploy your model in Docker Compose. .. toctree:: From c5016078d9f584ddee68635d67050a2589b2b15c Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 23 Mar 2020 11:15:37 +0100 Subject: [PATCH 16/27] fix tracker store configuration docs --- docs/api/tracker-stores.rst | 89 ++++++++++++--- .../docker/deploying-in-docker-compose.rst | 103 ++---------------- 2 files changed, 85 insertions(+), 107 deletions(-) diff --git a/docs/api/tracker-stores.rst b/docs/api/tracker-stores.rst index 9fa7db15674f..1e95df9b8291 100644 --- a/docs/api/tracker-stores.rst +++ b/docs/api/tracker-stores.rst @@ -34,31 +34,42 @@ SQLTrackerStore :Description: ``SQLTrackerStore`` can be used to store the conversation history in an SQL database. Storing your trackers this way allows you to query the event database by sender_id, timestamp, action name, - intent name and typename + intent name and typename. :Configuration: To set up Rasa Open Source with SQL the following steps are required: - 1. Add required configuration to your ``endpoints.yml``: + #. Add required configuration to your ``endpoints.yml``: .. code-block:: yaml tracker_store: type: SQL - dialect: "sqlite" # the dialect used to interact with the db + dialect: "postgresql" # the dialect used to interact with the db url: "" # (optional) host of the sql db, e.g. "localhost" - db: "rasa.db" # path to your db + db: "rasa" # path to your db username: # username used for authentication password: # password used for authentication query: # optional dictionary to be added as a query string to the connection URL driver: my-driver - 3. To start the Rasa server using your SQL backend, + #. To start the Rasa server using your SQL backend, add the ``--endpoints`` flag, e.g.: .. code-block:: bash rasa run -m models --endpoints endpoints.yml + + #. If deploying your model in Docker Compose, add the service to your ``docker-compose.yml``: + + .. code-block:: yaml + + postgres: + image: postgres:latest + + Set ``url: postgres`` in your tracker store endpoints to route requests to that service. + + :Parameters: - ``domain`` (default: ``None``): Domain object associated with this tracker store - ``dialect`` (default: ``sqlite``): The dialect used to communicate with your SQL backend. Consult the `SQLAlchemy docs `_ for available dialects. @@ -122,6 +133,8 @@ SQLTrackerStore and start the container. The ``dialect`` parameter with this setup will be ``oracle+cx_oracle``. Read more about :ref:`deploying-your-rasa-assistant`. +.. _redis-tracker-store: + RedisTrackerStore ~~~~~~~~~~~~~~~~~~ @@ -132,8 +145,8 @@ RedisTrackerStore :Configuration: To set up Rasa Open Source with Redis the following steps are required: - 1. Start your Redis instance - 2. Add required configuration to your ``endpoints.yml``: + #. Start your Redis instance + #. Add required configuration to your ``endpoints.yml``: .. code-block:: yaml @@ -145,12 +158,22 @@ RedisTrackerStore password: use_ssl: - 3. To start the Rasa server using your configured Redis instance, + #. To start the Rasa server using your configured Redis instance, add the ``--endpoints`` flag, e.g.: .. code-block:: bash rasa run -m models --endpoints endpoints.yml + + #. If deploying your model in Docker Compose, add the service to your ``docker-compose.yml``: + + .. code-block:: yaml + + redis: + image: redis:latest + + Set ``url: redis`` in your tracker store endpoints to route requests to that service. + :Parameters: - ``url`` (default: ``localhost``): The url of your redis instance - ``port`` (default: ``6379``): The port which redis is running on @@ -160,6 +183,8 @@ RedisTrackerStore - ``record_exp`` (default: ``None``): Record expiry in seconds - ``use_ssl`` (default: ``False``): whether or not to use SSL for transit encryption +.. _mongo-tracker-store: + MongoTrackerStore ~~~~~~~~~~~~~~~~~ @@ -168,8 +193,8 @@ MongoTrackerStore MongoDB is a free and open-source cross-platform document-oriented NoSQL database. :Configuration: - 1. Start your MongoDB instance. - 2. Add required configuration to your ``endpoints.yml`` + #. Start your MongoDB instance. + #. Add required configuration to your ``endpoints.yml`` .. code-block:: yaml @@ -184,12 +209,41 @@ MongoTrackerStore You can also add more advanced configurations (like enabling ssl) by appending a parameter to the url field, e.g. mongodb://localhost:27017/?ssl=true - 3. To start the Rasa server using your configured MongoDB instance, + #. To start the Rasa server using your configured MongoDB instance, add the :code:`--endpoints` flag, e.g.: .. code-block:: bash rasa run -m models --endpoints endpoints.yml + + #. If deploying your model in Docker Compose, add the service to your ``docker-compose.yml``: + + .. code-block:: yaml + + mongo: + image: mongo + environment: + MONGO_INITDB_ROOT_USERNAME: rasa + MONGO_INITDB_ROOT_PASSWORD: example + mongo-express: # this service is a MongoDB UI, and is optional + image: mongo-express + ports: + - 8081:8081 + environment: + ME_CONFIG_MONGODB_ADMINUSERNAME: rasa + ME_CONFIG_MONGODB_ADMINPASSWORD: example + + To route requests to this database, make sure to specify the URL as well as the specified user and + password: + + .. code-block:: yaml + + tracker_store: + type: mongod + url: mongodb://mongo:27017 + username: rasa + password: example + :Parameters: - ``url`` (default: ``mongodb://localhost:27017``): URL of your MongoDB - ``db`` (default: ``rasa``): The database name which should be used @@ -199,6 +253,8 @@ MongoTrackerStore - ``collection`` (default: ``conversations``): The collection name which is used to store the conversations +.. _custom-tracker-store: + Custom Tracker Store ~~~~~~~~~~~~~~~~~~~~ @@ -209,9 +265,9 @@ Custom Tracker Store .. autoclass:: rasa.core.tracker_store.TrackerStore :Steps: - 1. Extend the ``TrackerStore`` base class. Note that your constructor has to + #. Extend the ``TrackerStore`` base class. Note that your constructor has to provide a parameter ``url``. - 2. In your ``endpoints.yml`` put in the module path to your custom tracker store + #. In your ``endpoints.yml`` put in the module path to your custom tracker store and the parameters you require: .. code-block:: yaml @@ -221,3 +277,10 @@ Custom Tracker Store url: localhost a_parameter: a value another_parameter: another value + + #. If you are deploying in Docker Compose, you have two options to add this store to Rasa Open Source: + + - extending the Rasa image to include the module + - mounting the module as volume + + Make sure to add the corresponding service as well. diff --git a/docs/user-guide/docker/deploying-in-docker-compose.rst b/docs/user-guide/docker/deploying-in-docker-compose.rst index 7fbb8a19fe6e..0c1265cdc073 100644 --- a/docs/user-guide/docker/deploying-in-docker-compose.rst +++ b/docs/user-guide/docker/deploying-in-docker-compose.rst @@ -217,7 +217,7 @@ Then, reference the new image tag in your ``docker-compose.override.yml``: app: image: /: -Adding a Custom Tracker Store +Configuring a Tracker Store ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, all conversations are saved in memory. This means that all @@ -225,97 +225,12 @@ conversations are lost as soon as you restart the Rasa server. If you want to persist your conversations, you can use a different :ref:`Tracker Store `. -.. contents:: - :local: - :depth: 2 - -Using PostgreSQL as Tracker Store -################################# - -Start by adding PostgreSQL to your ``docker-compose.yml``: - - .. code-block:: yaml - - postgres: - image: postgres:latest - -Then add PostgreSQL to the ``tracker_store`` section of your endpoint -configuration ``config/endpoints.yml``: - - .. code-block:: yaml - - tracker_store: - type: sql - dialect: "postgresql" - url: postgres - db: rasa - -Using MongoDB as Tracker Store -############################## - -Start by adding MongoDB to your ``docker-compose.yml``. The following example -adds the MongoDB as well as a UI (you can skip this), which will be available -at ``localhost:8081``. Username and password for the MongoDB instance are -specified as ``rasa`` and ``example``. - - .. code-block:: yaml - - mongo: - image: mongo - environment: - MONGO_INITDB_ROOT_USERNAME: rasa - MONGO_INITDB_ROOT_PASSWORD: example - mongo-express: - image: mongo-express - ports: - - 8081:8081 - environment: - ME_CONFIG_MONGODB_ADMINUSERNAME: rasa - ME_CONFIG_MONGODB_ADMINPASSWORD: example - -Then add the MongoDB to the ``tracker_store`` section of your endpoints -configuration ``endpoints.yml``: - - .. code-block:: yaml - - tracker_store: - type: mongod - url: mongodb://mongo:27017 - username: rasa - password: example - -Then start all components with ``docker-compose up``. - -Using Redis as Tracker Store -############################ - -Start by adding Redis to your ``docker-compose.yml``: - - .. code-block:: yaml - - redis: - image: redis:latest - -Then add Redis to the ``tracker_store`` section of your endpoint -configuration ``endpoints.yml``: - - .. code-block:: yaml - - tracker_store: - type: redis - url: redis - -Using a Custom Tracker Store Implementation -########################################### - -If you have a custom implementation of a tracker store you have two options -to add this store to Rasa Open Source: - - - extending the Rasa image - - mounting it as volume +To add a tracker store to a Docker Compose deployment, you need to add a new +service to your ``docker-compose.yml`` and modify the ``endpoints.yml`` to add +the new tracker store, pointing to your new service. More information about how +to do so can be found in the tracker store documentation: -Then add the required configuration to your endpoint configuration -``endpoints.yml`` as it is described in :ref:`tracker-stores`. -If you want the tracker store component (e.g. a certain database) to be part -of your Docker Compose file, add a corresponding service and configuration -there. + - :ref:`sql-tracker-store` + - :ref:`redis-tracker-store` + - :ref:`mongo-tracker-store` + - :ref:`custom-tracker-store` From 01d708cfd4a05f9d534d50aec693288d110bbd91 Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 23 Mar 2020 22:18:27 +0100 Subject: [PATCH 17/27] clarify choosing a tag --- docs/user-guide/docker/building-in-docker.rst | 39 +++++++++---------- docs/user-guide/how-to-deploy.rst | 2 +- 2 files changed, 19 insertions(+), 22 deletions(-) diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index 40c5ca70a6ee..01b9d7682bbe 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -91,12 +91,7 @@ Customizing your Model Choosing a Tag ############## -To keep images as small as possible, we publish different tags of the ``rasa/rasa`` image -with different dependencies installed. See :ref:`choosing-a-pipeline` for more information -about depedencies. - -All tags start with a version -- the ``latest`` tag corresponds to the current master build. -The tags are: +All ``rasa/rasa`` image tags start with a version number. The tags are: - ``{version}`` - ``{version}-spacy-en`` @@ -104,15 +99,23 @@ The tags are: - ``{version}-mitie-en`` - ``{version}-full`` -The plain ``{version}`` tag includes all the dependencies you need to run the ``supervised_embeddings`` pipeline. -If you are using components with pre-trained word vectors, you need to choose the corresponding tag. -Alternatively, you can use the ``-full`` tag, which includes all pipeline dependencies. +The plain ``{version}`` tag includes all the dependencies you need to run the default pipeline created by ``rasa init``. +However, if you want to change the components in your pipeline, you may need extra dependencies. +To keep images as small as possible, we publish different tags of the ``rasa/rasa`` image +with different dependencies installed. See :ref:`choosing-a-pipeline` for more information +about pipeline dependencies. -.. note:: +If you are using components with pre-trained word vectors from spaCy or MITIE, you need to choose the corresponding tag. +You can see a list of all the versions and tags of the Rasa Docker image on `DockerHub `_. +You can also use the ``-full`` tag, which includes all possible pipeline dependencies. - You can see a list of all the versions and tags of the Rasa Docker image - `here `_. +If your model has a dependency that is not included in any of the tags (for example, a different spaCy language model), +you can build a docker image that extends the `rasa/rasa` image. +.. warning:: + + The ``latest`` tags correspond to the current master build. These tags are not recommended for use, + as they are not guaranteed to be stable. .. _model_training_docker: @@ -123,21 +126,15 @@ Edit the ``config.yml`` file to use the pipeline you want, and place your NLU and Core data into the ``data/`` directory. Now you can train your Rasa model by running: - .. code-block:: bash + .. parsed-literal:: - docker run \ - -v $(pwd):/app \ - rasa/rasa:latest-full \ - train \ - --domain domain.yml \ - --data data \ - --out models + docker run -v $(pwd):/app rasa/rasa:\ |release|-full train --domain domain.yml --data data --out models Here's what's happening in that command: - ``-v $(pwd):/app``: Mounts your project directory into the Docker container so that Rasa can train a model on your training data - - ``rasa/rasa:latest-full``: Use the Rasa image with the tag ``latest-full`` + - rasa/rasa:|release|-full: Use the Rasa image with the tag |release|-full - ``train``: Execute the ``rasa train`` command within the container. For more information see :ref:`command-line-interface`. diff --git a/docs/user-guide/how-to-deploy.rst b/docs/user-guide/how-to-deploy.rst index 7a250c537f9e..b57d7ce832da 100644 --- a/docs/user-guide/how-to-deploy.rst +++ b/docs/user-guide/how-to-deploy.rst @@ -74,7 +74,7 @@ Docker Compose You can also run Rasa X in a Docker Compose setup, without the cluster environment. We have a quick install script for doing so, as well as manual instructions for any custom setups. - - Default: Watch the `Masterclass Video `_ on deploying Rasa X or read the `Docker Compose Quick Install `_ docs. + - Default: Read the `Docker Compose Quick Install `_ docs or watch the `Masterclass Video `_ on deploying Rasa X. - Custom: Read the docs `Docker Compose Manual Install `_ documentation for full customization options. Rasa Open Source Only Deployment From 45a533a5276b791e05c907ca7dd8391ff5f6889e Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 23 Mar 2020 22:28:52 +0100 Subject: [PATCH 18/27] clarify actions folder for image building --- .../user-guide/docker/deploying-in-docker-compose.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/docker/deploying-in-docker-compose.rst b/docs/user-guide/docker/deploying-in-docker-compose.rst index 0c1265cdc073..6c7c8e166ca3 100644 --- a/docs/user-guide/docker/deploying-in-docker-compose.rst +++ b/docs/user-guide/docker/deploying-in-docker-compose.rst @@ -147,9 +147,12 @@ a different Docker registry, such as `Google Container Registry `_. To create your image: - - If your actions have any extra dependencies, create a list of them in a file, - ``actions/requirements-actions.txt``. - - Create a file named ``Dockerfile`` in your project directory, + + #. Move your actions code to a folder ``actions`` in your project directory. + Make sure to also add an empty ``actions/__init__.py`` file. + #. If your actions have any extra dependencies, create a list of them in a file, + ``actions/requirements-actions.txt``. + #. Create a file named ``Dockerfile`` in your project directory, in which you'll extend the official SDK image, copy over your code, and add any custom dependencies (if necessary). For example: @@ -170,7 +173,7 @@ To create your image: # Install extra requirements for actions code, if necessary (otherwise comment this out) RUN pip install -r requirements-actions.txt - # Copy actions code to working directory + # Copy actions folder to working directory COPY ./actions /app/actions # By best practices, don't run the code with root user From aae4e0899b21d3baa1384c1787f8c8a009bdfe4d Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 23 Mar 2020 22:31:34 +0100 Subject: [PATCH 19/27] use release insetad of latest in deploy in docker --- docs/user-guide/docker/deploying-in-docker-compose.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/user-guide/docker/deploying-in-docker-compose.rst b/docs/user-guide/docker/deploying-in-docker-compose.rst index 6c7c8e166ca3..ed2641122efd 100644 --- a/docs/user-guide/docker/deploying-in-docker-compose.rst +++ b/docs/user-guide/docker/deploying-in-docker-compose.rst @@ -67,12 +67,12 @@ Start by creating a file called ``docker-compose.yml``: Add the following content to the file: - .. code-block:: yaml + .. parsed-literal:: version: '3.0' services: rasa: - image: rasa/rasa:latest-full + image: rasa/rasa:\ |release|-full ports: - 5005:5005 volumes: @@ -88,13 +88,12 @@ The first service is the ``rasa`` service, which runs your Rasa server. To add the action server, add the image of your action server code. To learn how to deploy an action server image, see :ref:`building-an-action-server-image`. - .. code-block:: yaml - :emphasize-lines: 11-13 + .. parsed-literal:: version: '3.0' services: rasa: - image: rasa/rasa:latest-full + image: rasa/rasa:\ |release|-full ports: - 5005:5005 volumes: From 7962a66360f62bba209a914747070d7816fe1d39 Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 23 Mar 2020 22:39:07 +0100 Subject: [PATCH 20/27] use release and version instead of latest in build in docker --- docs/user-guide/docker/building-in-docker.rst | 16 ++++++++-------- .../docker/deploying-in-docker-compose.rst | 4 ++-- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index 01b9d7682bbe..34900ccadc22 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -91,7 +91,7 @@ Customizing your Model Choosing a Tag ############## -All ``rasa/rasa`` image tags start with a version number. The tags are: +All ``rasa/rasa`` image tags start with a version number. The current version is |release|. The tags are: - ``{version}`` - ``{version}-spacy-en`` @@ -110,7 +110,7 @@ You can see a list of all the versions and tags of the Rasa Docker image on `Doc You can also use the ``-full`` tag, which includes all possible pipeline dependencies. If your model has a dependency that is not included in any of the tags (for example, a different spaCy language model), -you can build a docker image that extends the `rasa/rasa` image. +you can build a docker image that extends the ``rasa/rasa`` image. .. warning:: @@ -134,7 +134,7 @@ Here's what's happening in that command: - ``-v $(pwd):/app``: Mounts your project directory into the Docker container so that Rasa can train a model on your training data - - rasa/rasa:|release|-full: Use the Rasa image with the tag |release|-full + - rasa/rasa:|release|-full: Use the Rasa image with the tag '|release|-full' - ``train``: Execute the ``rasa train`` command within the container. For more information see :ref:`command-line-interface`. @@ -202,11 +202,11 @@ In ``domain.yml``, add a section for custom actions, including your new action: After updating your domain and stories, you have to retrain your model: - .. code-block:: bash + .. parsed-literal:: docker run \ -v $(pwd):/app \ - rasa/rasa:latest-full \ + rasa/rasa:\ |release|-full \ train Your actions will run on a separate server from your Rasa server. First create a network to connect the two containers: @@ -217,13 +217,13 @@ Your actions will run on a separate server from your Rasa server. First create a You can then run the actions with the following command: - .. code-block:: bash + .. parsed-literal:: docker run -d \ -v $(pwd)/actions:/app/actions \ --net my-project \ --name action-server - rasa/rasa-sdk:latest + rasa/rasa-sdk:\ |version|.0 Here's what's happening in that command: @@ -233,7 +233,7 @@ Here's what's happening in that command: container so that the action server can run the code in the ``actions`` folder - ``net my-project``: Run the server on a specific network so that the rasa container can find it - ``--name action-server``: Gives the server a specific name for the rasa server to reference - - ``rasa/rasa-sdk:latest``: Uses the Rasa SDK image with the tag ``latest`` + - rasa/rasa-sdk:|version|.0 : Uses the Rasa SDK image with the tag |version|.0 Because the action server is running in detached mode, if you want to stop the container, diff --git a/docs/user-guide/docker/deploying-in-docker-compose.rst b/docs/user-guide/docker/deploying-in-docker-compose.rst index ed2641122efd..bd297565ee13 100644 --- a/docs/user-guide/docker/deploying-in-docker-compose.rst +++ b/docs/user-guide/docker/deploying-in-docker-compose.rst @@ -155,10 +155,10 @@ To create your image: in which you'll extend the official SDK image, copy over your code, and add any custom dependencies (if necessary). For example: - .. code-block:: docker + .. parsed-literal:: # Extend the official Rasa SDK image - FROM rasa/rasa-sdk:latest + FROM rasa/rasa-sdk:\ |version|.0 # Use subdirectory as working directory WORKDIR /app From a6b244a363e06f96efe43d85c786af1e66b224a2 Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 23 Mar 2020 22:49:12 +0100 Subject: [PATCH 21/27] version every docker command and restructure a bit --- docs/user-guide/docker/building-in-docker.rst | 87 +++++++++---------- 1 file changed, 43 insertions(+), 44 deletions(-) diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index 34900ccadc22..a3489cb66575 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -33,9 +33,9 @@ Just like in the :ref:`tutorial `, you'll use the ``rasa init`` c The only difference is that you'll be running Rasa inside a Docker container, using the image ``rasa/rasa``. To initialize your project, run: - .. code-block:: bash + .. parsed-literal:: - docker run -v $(pwd):/app rasa/rasa init --no-prompt + docker run -v $(pwd):/app rasa/rasa:\ |release| init --no-prompt What does this command mean? @@ -43,7 +43,7 @@ What does this command mean? in the Docker container. This means that files you create on your computer will be visible inside the container, and files created in the container will get synced back to your computer. -- ``rasa/rasa`` is the name of the docker image to run. +- ``rasa/rasa`` is the name of the docker image to run. '|release|' is the name of the tag, which specifies the version. - the Docker image has the ``rasa`` command as its entrypoint, which means you don't have to type ``rasa init``, just ``init`` is enough. @@ -74,9 +74,9 @@ Talking to Your Assistant To talk to your newly-trained assistant, run this command: - .. code-block:: bash + .. parsed-literal:: - docker run -it -v $(pwd):/app rasa/rasa shell + docker run -it -v $(pwd):/app rasa/rasa:\ |release| shell This will start a shell where you can chat to your assistant. Note that this command includes the flags ``-it``, which means that you are running @@ -85,9 +85,41 @@ For commands which require interactive input, like ``rasa shell`` and ``rasa int you need to pass the ``-it`` flags. +.. _model_training_docker: + +Training a Model +**************** + +If you edit the NLU or Core training data or edit the ``config.yml`` file, you'll need to +retrain your Rasa model. You can do so by running: + + .. parsed-literal:: + + docker run -v $(pwd):/app rasa/rasa:\ |release|-full train --domain domain.yml --data data --out models + +Here's what's happening in that command: + + - ``-v $(pwd):/app``: Mounts your project directory into the Docker + container so that Rasa can train a model on your training data + - rasa/rasa:|release|-full: Use the Rasa image with the tag '|release|-full' + - ``train``: Execute the ``rasa train`` command within the container. For more + information see :ref:`command-line-interface`. + +In this case, we've also passed values for the location of the domain file, training +data, and the models output directory to show how these can be customized. +You can also leave these out, since we are passing the default values. + +.. note:: + + When changing components in your ``config.yml``, you may introduce new dependencies and need a different image tag. + See :ref:`choosing-a-tag` for more information. + + Customizing your Model ********************** +.. _choosing-a-tag: + Choosing a Tag ############## @@ -117,34 +149,8 @@ you can build a docker image that extends the ``rasa/rasa`` image. The ``latest`` tags correspond to the current master build. These tags are not recommended for use, as they are not guaranteed to be stable. -.. _model_training_docker: - -Training a Model -################ - -Edit the ``config.yml`` file to use the pipeline you want, and place -your NLU and Core data into the ``data/`` directory. -Now you can train your Rasa model by running: - - .. parsed-literal:: - - docker run -v $(pwd):/app rasa/rasa:\ |release|-full train --domain domain.yml --data data --out models - -Here's what's happening in that command: - - - ``-v $(pwd):/app``: Mounts your project directory into the Docker - container so that Rasa can train a model on your training data - - rasa/rasa:|release|-full: Use the Rasa image with the tag '|release|-full' - - ``train``: Execute the ``rasa train`` command within the container. For more - information see :ref:`command-line-interface`. - -In this case, we've also passed values for the location of the domain file, training -data, and the models output directory to show how these can be customized. -You can also leave these out since we are passing the default values. - - Adding Custom Components -************************ +######################## If you are using a custom NLU component or policy ot your ``config.yml``, you have to add the module file to your Docker container. You can do this by either mounting the file or by including it in your @@ -154,7 +160,7 @@ environment variable ``PYTHONPATH=$PYTHONPATH:``. Adding Custom Actions -********************* +##################### To create more sophisticated assistants, you will want to use :ref:`custom-actions`. Continuing the example from above, you might want to add an action which tells @@ -204,10 +210,7 @@ After updating your domain and stories, you have to retrain your model: .. parsed-literal:: - docker run \ - -v $(pwd):/app \ - rasa/rasa:\ |release|-full \ - train + docker run -v $(pwd):/app rasa/rasa:\ |release| train Your actions will run on a separate server from your Rasa server. First create a network to connect the two containers: @@ -219,11 +222,7 @@ You can then run the actions with the following command: .. parsed-literal:: - docker run -d \ - -v $(pwd)/actions:/app/actions \ - --net my-project \ - --name action-server - rasa/rasa-sdk:\ |version|.0 + docker run -d -v $(pwd)/actions:/app/actions --net my-project --name action-server rasa/rasa-sdk:\ |version|.0 Here's what's happening in that command: @@ -250,9 +249,9 @@ Add this endpoint to your ``endpoints.yml``, referencing the ``--name`` you gave Now you can talk to your bot again via the ``shell`` command: - .. code-block:: bash + .. parsed-literal:: - docker run -it -v $(pwd):/app -p 5005:5005 --net my-project rasa/rasa shell + docker run -it -v $(pwd):/app -p 5005:5005 --net my-project rasa/rasa:\ |release| shell .. note:: From 5d10609d98ace83e22b602a3830479608876fc3c Mon Sep 17 00:00:00 2001 From: Ella Date: Mon, 23 Mar 2020 23:04:19 +0100 Subject: [PATCH 22/27] fix build warnings --- docs/user-guide/docker/deploying-in-docker-compose.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/docker/deploying-in-docker-compose.rst b/docs/user-guide/docker/deploying-in-docker-compose.rst index bd297565ee13..4c3537520911 100644 --- a/docs/user-guide/docker/deploying-in-docker-compose.rst +++ b/docs/user-guide/docker/deploying-in-docker-compose.rst @@ -152,8 +152,8 @@ To create your image: #. If your actions have any extra dependencies, create a list of them in a file, ``actions/requirements-actions.txt``. #. Create a file named ``Dockerfile`` in your project directory, - in which you'll extend the official SDK image, copy over your code, and add any custom dependencies (if necessary). - For example: + in which you'll extend the official SDK image, copy over your code, and add any custom dependencies (if necessary). + For example: .. parsed-literal:: From a581e5ae8dfa0b9894f367ee6595a65da5a583e9 Mon Sep 17 00:00:00 2001 From: Ella Rohm-Ensing Date: Tue, 24 Mar 2020 11:04:47 +0100 Subject: [PATCH 23/27] Update docs/user-guide/docker/building-in-docker.rst Co-Authored-By: Akela Drissner-Schmid <32450038+akelad@users.noreply.github.com> --- docs/user-guide/docker/building-in-docker.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index a3489cb66575..998bcb4b8fb8 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -152,7 +152,7 @@ you can build a docker image that extends the ``rasa/rasa`` image. Adding Custom Components ######################## -If you are using a custom NLU component or policy ot your ``config.yml``, you have to add the module file to your +If you are using a custom NLU component or policy in your ``config.yml``, you have to add the module file to your Docker container. You can do this by either mounting the file or by including it in your own custom image (e.g. if the custom component or policy has extra dependencies). Make sure that your module is in the Python module search path by setting the From 93ce50c262d5316307c006331ed74111d1276c04 Mon Sep 17 00:00:00 2001 From: Ella Date: Tue, 24 Mar 2020 11:17:54 +0100 Subject: [PATCH 24/27] use -full tag --- docs/user-guide/docker/building-in-docker.rst | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/user-guide/docker/building-in-docker.rst b/docs/user-guide/docker/building-in-docker.rst index a3489cb66575..192bbb7f72d4 100644 --- a/docs/user-guide/docker/building-in-docker.rst +++ b/docs/user-guide/docker/building-in-docker.rst @@ -35,7 +35,7 @@ the image ``rasa/rasa``. To initialize your project, run: .. parsed-literal:: - docker run -v $(pwd):/app rasa/rasa:\ |release| init --no-prompt + docker run -v $(pwd):/app rasa/rasa:\ |release|-full init --no-prompt What does this command mean? @@ -43,7 +43,8 @@ What does this command mean? in the Docker container. This means that files you create on your computer will be visible inside the container, and files created in the container will get synced back to your computer. -- ``rasa/rasa`` is the name of the docker image to run. '|release|' is the name of the tag, which specifies the version. +- ``rasa/rasa`` is the name of the docker image to run. '|release|-full' is the name of the tag, + which specifies the version and dependencies. - the Docker image has the ``rasa`` command as its entrypoint, which means you don't have to type ``rasa init``, just ``init`` is enough. @@ -76,7 +77,7 @@ To talk to your newly-trained assistant, run this command: .. parsed-literal:: - docker run -it -v $(pwd):/app rasa/rasa:\ |release| shell + docker run -it -v $(pwd):/app rasa/rasa:\ |release|-full shell This will start a shell where you can chat to your assistant. Note that this command includes the flags ``-it``, which means that you are running @@ -109,12 +110,6 @@ In this case, we've also passed values for the location of the domain file, trai data, and the models output directory to show how these can be customized. You can also leave these out, since we are passing the default values. -.. note:: - - When changing components in your ``config.yml``, you may introduce new dependencies and need a different image tag. - See :ref:`choosing-a-tag` for more information. - - Customizing your Model ********************** @@ -126,24 +121,29 @@ Choosing a Tag All ``rasa/rasa`` image tags start with a version number. The current version is |release|. The tags are: - ``{version}`` +- ``{version}-full`` - ``{version}-spacy-en`` - ``{version}-spacy-de`` - ``{version}-mitie-en`` -- ``{version}-full`` -The plain ``{version}`` tag includes all the dependencies you need to run the default pipeline created by ``rasa init``. -However, if you want to change the components in your pipeline, you may need extra dependencies. -To keep images as small as possible, we publish different tags of the ``rasa/rasa`` image -with different dependencies installed. See :ref:`choosing-a-pipeline` for more information -about pipeline dependencies. -If you are using components with pre-trained word vectors from spaCy or MITIE, you need to choose the corresponding tag. -You can see a list of all the versions and tags of the Rasa Docker image on `DockerHub `_. -You can also use the ``-full`` tag, which includes all possible pipeline dependencies. +The ``{version}-full`` tag includes all possible pipeline dependencies, allowing you to change your ``config.yml`` +as you like without worrying about missing dependencies. The plain ``{version}`` tag includes all the +dependencies you need to run the default pipeline created by ``rasa init``. + +To keep images as small as possible, we also publish different tags of the ``rasa/rasa`` image +with different dependencies installed. See :ref:`choosing-a-pipeline` for more dependency information +specific to your pipeline. For example, if you are using components with pre-trained word vectors from spaCy or +MITIE, you should choose the corresponding tag. If your model has a dependency that is not included in any of the tags (for example, a different spaCy language model), you can build a docker image that extends the ``rasa/rasa`` image. +.. note:: + + You can see a list of all the versions and tags of the Rasa Open Source + Docker image on `DockerHub `_. + .. warning:: The ``latest`` tags correspond to the current master build. These tags are not recommended for use, @@ -210,7 +210,7 @@ After updating your domain and stories, you have to retrain your model: .. parsed-literal:: - docker run -v $(pwd):/app rasa/rasa:\ |release| train + docker run -v $(pwd):/app rasa/rasa:\ |release|-full train Your actions will run on a separate server from your Rasa server. First create a network to connect the two containers: @@ -251,7 +251,7 @@ Now you can talk to your bot again via the ``shell`` command: .. parsed-literal:: - docker run -it -v $(pwd):/app -p 5005:5005 --net my-project rasa/rasa:\ |release| shell + docker run -it -v $(pwd):/app -p 5005:5005 --net my-project rasa/rasa:\ |release|-full shell .. note:: From 9ca5716938ddfe302395c476dbe4aec29f527256 Mon Sep 17 00:00:00 2001 From: Ella Date: Tue, 24 Mar 2020 11:40:35 +0100 Subject: [PATCH 25/27] clarify how to direct endpoints to service, add a custom tracker store, and fix oracle documentation versioning --- docs/api/tracker-stores.rst | 128 ++++++++++++++++++++++++++---------- 1 file changed, 94 insertions(+), 34 deletions(-) diff --git a/docs/api/tracker-stores.rst b/docs/api/tracker-stores.rst index 1e95df9b8291..f4f349074a96 100644 --- a/docs/api/tracker-stores.rst +++ b/docs/api/tracker-stores.rst @@ -67,7 +67,21 @@ SQLTrackerStore postgres: image: postgres:latest - Set ``url: postgres`` in your tracker store endpoints to route requests to that service. + To route requests to the new service, make sure that the ``url`` in your ``endpoints.yml`` + references the service name: + + .. code-block:: yaml + :emphasize-lines: 4 + + tracker_store: + type: SQL + dialect: "postgresql" # the dialect used to interact with the db + url: "postgres" + db: "rasa" # path to your db + username: # username used for authentication + password: # password used for authentication + query: # optional dictionary to be added as a query string to the connection URL + driver: my-driver :Parameters: @@ -94,40 +108,46 @@ SQLTrackerStore Create a sequence in the database with the following command, where username is the user you created (read more about creating sequences `here `__): - .. code-block:: sql + .. code-block:: sql - CREATE SEQUENCE username.events_seq; + CREATE SEQUENCE username.events_seq; Next you have to extend the Rasa Open Source image to include the necessary drivers and clients. First download the Oracle Instant Client from `here `__, 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``: - .. code-block:: bash - - FROM rasa/rasa:|version|-full - # 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 - 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 + .. parsed-literal:: + + FROM rasa/rasa:\ |release|-full + + # 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 + 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: - .. code-block:: bash + .. parsed-literal:: - docker build . -t rasa-oracle:|version|-oracle-full + docker build . -t rasa-oracle:\ |release|-oracle-full Now you can configure the tracker store in the ``endpoints.yml`` as described above, and start the container. The ``dialect`` parameter with this setup will be ``oracle+cx_oracle``. @@ -172,7 +192,19 @@ RedisTrackerStore redis: image: redis:latest - Set ``url: redis`` in your tracker store endpoints to route requests to that service. + To route requests to the new service, make sure that the ``url`` in your ``endpoints.yml`` + references the service name: + + .. code-block:: yaml + :emphasize-lines: 3 + + tracker_store: + type: redis + url: + port: + db: + password: + use_ssl: :Parameters: - ``url`` (default: ``localhost``): The url of your redis instance @@ -233,16 +265,20 @@ MongoTrackerStore ME_CONFIG_MONGODB_ADMINUSERNAME: rasa ME_CONFIG_MONGODB_ADMINPASSWORD: example - To route requests to this database, make sure to specify the URL as well as the specified user and - password: + To route requests to this database, make sure to set the ``url`` in your ``endpoints.yml`` as the service name, + and specify the user and password: - .. code-block:: yaml + .. code-block:: yaml + :emphasize-lines: 3, 5-6 + + tracker_store: + type: mongod + url: mongodb://mongo:27017 + db: + username: + password: + auth_source: - tracker_store: - type: mongod - url: mongodb://mongo:27017 - username: rasa - password: example :Parameters: - ``url`` (default: ``mongodb://localhost:27017``): URL of your MongoDB @@ -283,4 +319,28 @@ Custom Tracker Store - extending the Rasa image to include the module - mounting the module as volume - Make sure to add the corresponding service as well. + Make sure to add the corresponding service as well. For example, mounting it as a volume would look like so: + + ``docker-compose.yml``: + + .. code-block:: yaml + :emphasize-lines: 5-7 + + rasa: + + volumes: + - + - ./path/to/your/module.py:/app/path/to/your/module.py + custom-tracker-store: + image: custom-image:tag + + ``endpoints.yml``: + + .. code-block:: yaml + :emphasize-lines: 3 + + tracker_store: + type: path.to.your.module.Class + url: custom-tracker-store + a_parameter: a value + another_parameter: another value From d9e20db310740078ade357dd21dd34a45a6a0e03 Mon Sep 17 00:00:00 2001 From: Ella Date: Tue, 24 Mar 2020 12:09:21 +0100 Subject: [PATCH 26/27] fix reference in changelog --- changelog/5404.doc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog/5404.doc.rst b/changelog/5404.doc.rst index d27dc40af44c..9913489c5c5b 100644 --- a/changelog/5404.doc.rst +++ b/changelog/5404.doc.rst @@ -2,4 +2,4 @@ Explain how to run commands as ``root`` user in Rasa SDK Docker images since ver ``1.8.0``. Since version ``1.8.0`` the Rasa SDK Docker images does not longer run as ``root`` user by default. For commands which require ``root`` user usage, you have to switch back to the ``root`` user in your Docker image as described in -:ref:`deploying-your-rasa-assistant_custom-dependencies`. +:ref:`building-an-action-server-image`. From 2e51c31677e20b036dbd5028a2fa7fad652600b7 Mon Sep 17 00:00:00 2001 From: Ella Date: Tue, 24 Mar 2020 12:57:16 +0100 Subject: [PATCH 27/27] fix changelog ... again --- CHANGELOG.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 75e0b9ada835..90821382542c 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -32,7 +32,7 @@ Improved Documentation ``1.8.0``. Since version ``1.8.0`` the Rasa SDK Docker images does not longer run as ``root`` user by default. For commands which require ``root`` user usage, you have to switch back to the ``root`` user in your Docker image as described in - :ref:`deploying-your-rasa-assistant_custom-dependencies`. + :ref:`building-an-action-server-image`. - `#5402 `_: Made improvements to Building Assistants tutorial