Installation Guide

Windows

To get started on Windows, install the Windows Subsystem for Linux (WSL). Open a command prompt and run the following command:

wsl --install

Follow the on-screen instructions to complete the installation process.

Windows & Linux

Next, you will need to install Docker Desktop. Simply download and install Docker, and follow the steps provided during the installation process.

Creating the Compose File

To set up the environment for your application, create a compose.yaml file in the same directory where you cloned the repository. This file will contain configuration details to create a multi-container application. Here's a sample configuration for the CoCo application:

services:
  coco-db:
    container_name: coco-db
    image: mongo
    restart: always
    networks:
      - coco-net

  coco:
    container_name: coco
    image: pstlab/coco
    build:
      context: .
    ports:
      - "8080:8080"
    networks:
      - coco-net
    depends_on:
      - coco-db
    restart: always
    environment:
      - MONGODB_HOST=coco-db

networks:
  coco-net:

This file defines two services: one for the MongoDB database and another for the CoCo application server. The two services are connected via a custom network called coco-net.

Transformers

CoCo can use transformers to define the reactive behavior of the system. In particular, CoCo can be integrated with Rasa transformers to enable reactive behaviour definition through stories. To enable this feature, you need to compile CoCo with the ENABLE_TRANSFORMER flag set to ON.

Clone the repository from GitHub, including all submodules, by running the following command in your terminal:

git clone --recursive -b memory https://github.com/ratioSolver/cocoGUI

This will download the source code along with any required submodules for the project.

Additionally, you need to provide the path to the Rasa transformers in the TRANSFORMER_HOST environment variable. Here's an example configuration:

services:
  coco-db:
    container_name: coco-db
    image: mongo
    restart: always
    networks:
      - coco-net

  coco:
    container_name: coco
    build:
      context: .
      args:
        - ENABLE_TRANSFORMER=ON
    ports:
      - "8080:8080"
    networks:
      - coco-net
    depends_on:
      - coco-db
    restart: always
    environment:
      - MONGODB_HOST=coco-db
      - TRANSFORMER_HOST=<transformer-host>

networks:
  coco-net:

Replace <transformer-host> with the path to the Rasa transformers.

Running a Rasa server in a Docker container

To run a Rasa server in a Docker container, you can create a new Rasa project and add the following Dockerfile to the project directory:

FROM rasa/rasa

COPY . /app

WORKDIR /app

RUN rasa train

CMD ["rasa", "run", "-m", "models", "--enable-api"]

This Dockerfile will build a Docker image based on the official Rasa image, copy the project files to the container, train the model, and start the Rasa server.

You can then include the path to the Rasa server in the TRANSFORMER_HOST environment variable in the CoCo configuration file:

services:
  coco-db:
    container_name: coco-db
    image: mongo
    restart: always
    networks:
      - coco-net

  coco-transformer:
    container_name: coco-transformer
    image: rasa/rasa:3.6.20-full
    restart: always
    networks:
      - coco-net
    volumes:
      - ./:/app
    command:
      - run
      - --enable-api

  coco:
    container_name: coco
    build:
      context: .
      args:
        - ENABLE_TRANSFORMER=ON
    ports:
      - "8080:8080"
    networks:
      - coco-net
    depends_on:
      - coco-db
      - coco-transformer
    restart: always
    environment:
      - MONGODB_HOST=coco-db
      - TRANSFORMER_HOST=coco-transformer

Running the Application

Once the configuration file is ready, navigate to the directory where the compose.yaml file is located and run the following command:

docker compose up -d

Docker will automatically download the MongoDB image and build the CoCo server from the source code. It will then create and start two containers: coco-db and coco.

You can verify that the application is running successfully by visiting:

http://localhost:8080

If everything is set up correctly, you should be able to interact with the CoCo server through your browser.

System Configuration

The compose.yaml file maps port 8080 on the CoCo server to port 8080 on the host machine. If port 8080 is already in use on your host machine, or if you'd prefer to expose the service on a different port, you can easily modify the service configuration in the compose.yaml file.

To do this, update the coco service configuration by changing the 8080:8080 mapping to <desired-port>:8080, where <desired-port> is the new port number you want to use on your host machine.

For example, if you want to use port 9090 on the host machine, you would modify the configuration like this:

ports:
  - "9090:8080"

After making this change, the CoCo server will be accessible on http://localhost:9090 instead of http://localhost:8080.

Make sure to restart your Docker containers for the changes to take effect:

docker compose down
docker compose up -d

This will ensure that the updated port mapping is applied correctly.