docs: Update README and CONTRIBUTING instructions

* Update GitHub repo link
* Run all instructions inside the Poetry environment for simplicity
* Add insstructions for local development
* Add note about running tests on Mac

Signed-off-by: Phoevos Kalemkeris <[email protected]>

Author: phoevos

CONTRIBUTING.md

@@ -8,8 +8,8 @@ getting you started.
 1. Clone the repository:
 
     ```shell
-    git clone https://github.com/CogStack/CogStack-ModelGateway.git cms-gateway
-    cd cms-gateway
+    git clone https://github.com/CogStack/cogstack-model-gateway.git
+    cd cogstack-model-gateway
     ```
 
 2. Install Poetry if you haven't already:
@@ -24,32 +24,58 @@ getting you started.
     poetry install --with dev
     ```
 
-## Pre-commit Hooks
-
-We use pre-commit hooks to ensure code quality. To set them up, follow these steps:
-
-1. Install pre-commit if you haven't already:
+4. Activate the virtual environment:
 
     ```shell
-    pip install pre-commit
+    eval $(poetry env activate)
     ```
 
-2. Install the pre-commit hooks to your local Git repository:
+## Pre-commit Hooks
+
+We use pre-commit hooks to ensure code quality. To set them up, follow these steps:
+
+1. Install the pre-commit hooks to your local Git repository:
 
     ```shell
     pre-commit install
     ```
 
-3. (optional) To run the pre-commit hooks manually on all files, use:
+2. (optional) To run the pre-commit hooks manually on all files, use:
 
     ```shell
     pre-commit run --all-files
     ```
 
+## Running
+
+To run the project locally, the [run_local.py](./run_local.py) script is provided as a shortcut for
+spinning up the required external services (e.g. PostgreSQL, RabbitMQ, MinIO) as Docker containers
+and starting the Gateway, Scheduler, and Ripper as separate processes on the host machine. It also
+watches for changes in the codebase and restarts the services when necessary. Before running the
+script, ensure you have configured the environment with the required variables, as described in the
+[Installation](./README.md#installation) section of the README, and then execute the following
+inside the virtual environment:
+
+```shell
+python run_local.py
+```
+
+Note that the script is meant as a convenience tool for local development, therefore coming with no
+quality guarantees, and should not be used in production.
+
 ## Testing
 
-To run the tests, use the following command:
+To run the tests, execute the following command inside the virtual environment:
 
 ```shell
-poetry run pytest
+pytest
 ```
+
+### On Mac
+
+If you're running the integration tests on Mac you may need to take some additional steps to ensure
+that the host machine can access the Docker containers. This is because Docker for Mac runs in a
+virtual machine and, as a result, the containers are not directly accessible from the host. Given
+that the services running as part of the integration tests use IP addresses to communicate with the
+containers, an easy solution to avoid manual configuration would be using a tool like
+[docker-mac-net-connect](https://github.com/chipmk/docker-mac-net-connect).

README.md

@@ -70,16 +70,22 @@ CMG_SCHEDULER_MAX_CONCURRENT_TASKS=1
 # Postgres
 CMG_DB_USER=admin
 CMG_DB_PASSWORD=admin
+CMG_DB_HOST=postgres
+CMG_DB_PORT=5432
 CMG_DB_NAME=cmg_tasks
 
 # RabbitMQ
 CMG_QUEUE_USER=admin
 CMG_QUEUE_PASSWORD=admin
+CMG_QUEUE_HOST=rabbitmq
+CMG_QUEUE_PORT=5672
 CMG_QUEUE_NAME=cmg_tasks
 
 # MinIO
 CMG_OBJECT_STORE_ACCESS_KEY=admin
 CMG_OBJECT_STORE_SECRET_KEY=admin123
+CMG_OBJECT_STORE_HOST=minio
+CMG_OBJECT_STORE_PORT=9000
 CMG_OBJECT_STORE_BUCKET_TASKS=cmg-tasks
 CMG_OBJECT_STORE_BUCKET_RESULTS=cmg-results