.. _installation: Platform Installation Instructions ================================== This document is for developers / sysadmins who want to install the Rasa platform on premise or on a private cloud. At a high level, what you need to do is first install Rasa Platform on a server, and then put your own application in a docker container to run alongside it. .. note:: Rasa uses docker compose to manage the lifecycle of the containers. The **installation script should be used to provision a new server**. If you want to run the application alongside other software on an existing server, you should consider installing docker compose manually. Quickstart ---------- 1. copy the license file to the server .. code-block:: bash scp rasa_platform.yml example.com:~/rasa_platform.yml 2. Download and run the install script **on the server**: .. code-block:: bash curl -sSL -o install.sh https://storage.googleapis.com/rasa-releases/stable/install.sh sudo bash ./install.sh Replace ``stable`` with a specific version number if you want to install a specific version. 3. Start the platform .. code-block:: bash cd /etc/rasaplatform sudo docker-compose up -d 4. Create a platform user you can use to login .. code-block:: bash cd /etc/rasaplatform sudo python rasa_commands.py create admin USER PASSWORD Detailed Setup -------------- Rasa Platform is built as a collection of docker containers. Here we provide suggested hardware for running on a single server. Hardware & OS Requirements ^^^^^^^^^^^^^^^^^^^^^^^^^^ We recommend 8Gb RAM & 2-6 vCPUs for optimal performance. 4Gb RAM is the bare minimum. Your server should also have 100 Gb Disk space available. You will need a server running a modern Linux distribution that can run docker. The following OS’s work with the easy install script below: - Debian 7.7+ - Ubuntu 14.04 / 15.10 / 16.04 For any **other operating systems, please follow the manual installation instructions**. As long as docker is available for your operating system, Rasa Platform should run fine. Firewall ^^^^^^^^ Make sure the following ports are open: +------+-----------------+--------------------------------------------+ | Port | Service | Description | +======+=================+============================================+ | 443 | HTTPS | Web application over HTTPS access. | +------+-----------------+--------------------------------------------+ | 80 | HTTP | Web application access. | +------+-----------------+--------------------------------------------+ | 22 | SSH | SSH access. | +------+-----------------+--------------------------------------------+ If you install on **Google Cloud** this means: - make sure to check "Allow HTTP traffic" as well as "Allow HTTPS traffic" in the firewall settings of the VM instance. Prepare the installation ^^^^^^^^^^^^^^^^^^^^^^^^ Before you can install Rasa Platform, you need to have a license file. We will send you that file, it is named ``rasa_platform.yml``. It contains licensing information as well as configuration parameters. Make sure to **upload the license file to the server**, e.g. using .. code-block:: bash scp rasa_platform.yml HOSTNAME:~/rasa_platform.yml where ``HOSTNAME`` is the hostname or ip of your server. Install Docker Compose ^^^^^^^^^^^^^^^^^^^^^^ Rasa uses docker compose to spin up a collection of docker containers that combined make up the platform. You can either install a specific release, or use ``latest`` which corresponds to the most recent release (we recommend pinning a specific version though). Download the install script and run it. Make sure the current directory contains the license file: .. code-block:: bash curl -sSL -o install.sh https://storage.googleapis.com/rasa-releases/latest/install.sh sudo bash ./install.sh The installation script will install docker compose and ansible. ansible is a popular tool for automation - it will download the docker compose setup as well as prepare the environment for docker to run in. The platform related files will be installed into ``/etc/rasaplatform``. This includes credentials to login to the docker registry under ``/etc/rasaplatform/gcr_auth.json``. .. note:: Although, this is the easiest way to get your server ready to run the platform you can also follow the manual steps which will walk you through a couple more steps but will give you more control over the setup. Accept the terms and conditions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To accept the terms and conditions, run ``echo "${USER} $(date)" > /etc/rasaplatform/terms/agree.txt``. You can find the terms `here `_. Start the application ^^^^^^^^^^^^^^^^^^^^^ After you have successfully installed the platform you can now start it: .. code-block:: bash cd /etc/rasaplatform sudo docker-compose up -d This will run the platform in the background (due to ``-d``) and the application will continue to run even if you log out of the server. Create a User ^^^^^^^^^^^^^ To login into the platform, you need to create user accounts. At first, it is best to create at least one administrator account. To do so run: .. code-block:: bash cd /etc/rasaplatform sudo python rasa_commands.py create admin USER PASSWORD replacing the ``USER`` and ``PASSWORD`` fields, for example ``python rasa_commands.py create admin admin PasswOrd``. To create non-admin users, just replace ``admin`` with ``user``: .. code-block:: bash sudo python rasa_commands.py create user USER PASSWORD Test Your Login ^^^^^^^^^^^^^^^ Visit ``http://HOSTNAME`` in a web browser, and log in with the username & password entered in the previous command. Installing Updates ^^^^^^^^^^^^^^^^^^ How about: .. code-block:: bash curl -sSL -o install.sh https://storage.googleapis.com/rasa-releases/VERSION/install.sh sudo bash ./install.sh replacing ``VERSION`` with the version you want to install. .. warning:: Be aware, that during the update the following files will be overwritten: - ``/etc/rasaplatform/docker-compose.yml`` - ``/etc/rasaplatform/.env`` Make sure there are no changes in these files that you still need. E.g. instead of directly modifying ``docker-compose.yml`` you should rather create a new file called ``docker-compose.override.yml``. Docker will automatically take that file into account and override any attributes in ``docker-compose.yml`` with changes from the override file. Next Steps ^^^^^^^^^^ Now that you have the main pieces of the platform installed, you can go ahead and run the :ref:`example_application`. Manual Installation ------------------- 1. Make sure ``python``, ``docker``, and ``docker compose`` are installed on your platform. Detailed instructions can be found in the `docker documentation `_. You should be able to run .. code-block:: bash docker-compose --version 2. Create the project directory and switch to it: .. code-block:: bash mkdir /etc/rasaplatform cd /etc/rasaplatform 3. Download the platform files (``docker-compose.yml`` and ``rasa_commands.py``) that contain the containers and their setup (replacing ``latest`` with the version to install): .. code-block:: bash wget -qO docker-compose.yml https://storage.googleapis.com/rasa-releases/latest/docker-compose.yml wget -qO rasa_commands.py https://storage.googleapis.com/rasa-releases/latest/rasa_commands.py 4. Create the authentication file to download containers from the docker registry. To authenticated with the registry that contains the platform containers, you need to create a file in ``/etc/rasaplatform/gcr-auth.json`` that contains the JSON of the field ``docker_registry_license`` from your license. Make sure to copy everything between the outer ``"`` of the ``docker_registry_license`` key to that file. The contents of ``/etc/rasaplatform/gcr-auth.json`` should look like this: .. code-block:: json { "type": "service_account", "project_id": "rasa-platform", "private_key_id": "sdferw234qadst423qafdgxhw", "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvfwrt423qwadsfghtzw0BAQEFAASCBKgwggSkAgEAAoIBAQCgt338FkWbW13dghtzew4easdf5wAi15jrA9t4uOk8dghrtze4weasfgdhtAFZNfrLgvr2\nPBTu1lAJDLo136ZGTdMKi+/TuRqrIMg/sr8q0Ungish8v6t5Jb4gsjBi9StytCT4\nhWXDL3qeadfsgeDOudl6c3iMzylBws+VffrFfaZWjDpGtxmlYwIUa2e\noNSe7BYLnY9tDrX3zrP/wu/6FPbbGkBjguDG1l3Kx7l1wmiPtK5lIhjt+k7Oyx/u\nd6+gvfs+7RX9wUxnZT/tLggybYdsr8BA1Pqr0hDmhdDl7tjXVTmGLG+1/+lXVGFc\nqKEg+uLXAgMBAAECggEAESzwRK0Cp62LgBjInk+jvTmMI4lYP/XTnfk0TNwyiLxd\nT7mkw/TzkSVRifZ37lBQ6BS6BiqBJherh1N4xI+DF9HUN/wHR93QTyu7p8umlcxC\nlPV0KE4b5ZMfWvRG4y236cRGly9urcBNGoFzFHl8pd2iS5DMqZOYpSXY+qvkXTKE\nUOm5mVSs4S4Qa9cHL+jWXCvY0789fG1GrT+L3Fn+StKacgQuBnN1krYFYBSjCAh8\nsnSdjkvGguw/6OApPHd8HqkHtjU0PD67uU5QIm5N1bmz9KT4s9Pm+WbCinEstIiN\nIfln5ikmHcMAiIS0gzSnZavsY21PsDHBkD8SUO7CTQKBgQDgMPhx0TsB/oVH/SnU\nt3oTME+tfAKI69tozX02jHj6DY/vDpI1hXNmb4oMOos5+3ulborHqnso9za1RgV7\nm2N04QQVfzYEuZzJzXL11SHvBYVjHkXYy6HR5GhnPmwA+CzrDNy2/oYxlaqH7TBA\nR+f7IHToIPKGCVrhCJztlAgzIwKBgQC3hQNclIQ5Iw0gm9Rr8zAP/YoRJdiUSYtv\nNBmav+dTTSkPh51Bomj/J4Rrg8OLvHG5U79pmzbQdIFGYGKlR0l4/QepKpbaGm7x\nM/gRp/GXu9sN8LgI+h+FskCYi4cuqDjQ9L2S0gwMre4witmeVSIiBxLWxS7mvkZX\nWRW58ml2vQKBgBozPuW2SQobn6HhIUFdy+NwMu+YXYd44ORnl2mHkx/N8/NBJa8h\nkHH5OQ3izaCSFkooGAnrj4cjFP6sVzmx2DaxkVOd0UdOFdezreqy5MtVPthtkkYa\nzieEZPsj3WVjm4RAtY6hQjeLQSmve4MXpDHCAkeaih1F/Jvt8MEHGso3AoGBAJez\nTioTYpFQliNkbN2nMw2kyaKPJE6/1JDiAmBXTcMgP1blBWsh86UnZ2DwlI5IAcHu\npoWHlnIOPGaOejyhhuyKTPDbkcNMonSkPuVpbF2/Hb6SQ664A6KizJ7Mh7xbtkuU\nY7igBPHePMzHmkg1m3eBXWNHsBNxKfg+XaVN6zwJAoGBAN6VhGMmyDcn0GqkkP6d\nrSsQ0Ig7L4PnU633oYWoGWa8q/XYiFbcACMFynMbrmHG+/0c3Iwt32bi3th60Cwb\nT66yqmv4MaT72+EfQHxiLxnUxhqSpBXM0eoXbyvDg97Zp/slsYvGGLjONmmretlE\nsjAsuAH4Iz1XdfdenzGnyBZH\n-----END PRIVATE KEY-----\n", "client_email": "company@rasa-platform.iam.gserviceaccount.com", "client_id": "114123456713428149", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://accounts.google.com/o/oauth2/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/company%40rasa-platform.iam.gserviceaccount.com" } 5. Login to the docker registry .. code-block:: bash sudo docker login -u _json_key -p "$(cat /etc/rasaplatform/gcr-auth.json)" https://gcr.io 6. Create the docker environment file in ``/etc/rasaplatform/.env`` with the following content: .. code-block:: ini RASA_PYPI_PASSWORD= RASA_PYPI_USER= RASA_NLU_TOKEN= RASA_CORE_TOKEN= PASSWORD_SALT= TOKEN_SALT= MONGO_PASSWORD= Filling in the values of ```` and ```` from your license file. For ```` please use secure strings, e.g. randomly generated character sequences. For the token and password salt fields, enter any string of your choice. These will be used to hash passwords. Note that if you change these you will have to create new logins for everyone. You will also need to set a Rasa NLU and Rasa Core Token. These are needed to ensure only you have access. .. note:: Make sure to generate a **different** unique for each field! E.g. running this multiple times: .. code-block:: bash openssl rand -base64 12 7. Start up the platform (``-d`` will run the platform in the background): .. code-block:: bash sudo docker-compose up -d