fix: Add details into readme

README.md

@@ -5,26 +5,51 @@
 
 * Create `.env` file with the following variables and required values:
 
-```env
-RABBITMQ_HOSTNAME=192.254.254.254
-RABBITMQ_USERNAME=guest
-RABBITMQ_PASSWORD=guest
-EXCHANGE_NAME=x_assessment
-DURABLE_QUEUE_NAME=q_csharp
-BINDING_KEYS=csharp
-DEFAULT_BINDING_KEY=default_env
-```
-
-* Configure your machine to add an alias IP address to en0 (or whatever network device you are using) as the value specified to the key `RABBITMQ_HOSTNAME` in the .env file before. On MacOS, you can use: `sudo ifconfig en0 alias 192.254.254.254 255.255.255.0`
-
-* Run RabbitMQ server:
-
-`docker run -d --hostname my-rabbit --name some-rabbit -p 5672:5672 -p 15672:15672 rabbitmq:3`
-
-* Enable RabbitMQ management plugin:
-
-`docker exec -t some-rabbit rabbitmq-plugins enable rabbitmq_management`
-
-
-
-TBC
+  ```env
+  RABBITMQ_HOSTNAME=192.254.254.254
+  RABBITMQ_USERNAME=guest
+  RABBITMQ_PASSWORD=guest
+
+  HOST_XFS_VOLUME=/some/path
+  CONTAINER_NAME=Some-Docker-Container-Name
+  ```
+
+  * `RABBITMQ_HOSTNAME`, `RABBITMQ_USERNAME`, and `RABBITMQ_PASSWORD` provide details needed to access the rabbitmq.
+  * `HOST_XFS_VOLUME` is the path to the location where overseer containers will store their work. When multiple overseer instances are run this path needs to be unique for each instance. Overseer will create `sandbox` and `output` folders in this location.
+  * `CONTAINER_NAME` is optional (defaults to `overseer-container`) and provides the name of the container that overseer creates. If there are multiple overseer instances then they must have unique container names.
+
+* Easiest option is to setup rabbitmq alongside overseer in the same docker network, and have it setup to run with the management interface.
+
+* Alternatively:
+  * Configure your machine to add an alias IP address to en0 (or whatever network device you are using) as the value specified to the key `RABBITMQ_HOSTNAME` in the .env file before. On MacOS, you can use: `sudo ifconfig en0 alias 192.254.254.254 255.255.255.0`
+  * Run RabbitMQ server:
+
+    `docker run -d --hostname my-rabbit --name some-rabbit -p 5672:5672 -p 15672:15672 rabbitmq:3`
+
+  * Enable RabbitMQ management plugin:
+
+    `docker exec -t some-rabbit rabbitmq-plugins enable rabbitmq_management`
+
+* Run overseer using:
+    `bundle exec ruby ./app.rb`
+
+# Basic operation
+
+* When overseer starts is listens to the **q.tasks** queue on the **ontrack** exchange of the rabbitmq and awaits any messages marked as **task.submission**. When a submission is received the message triggers action in overseer.
+* Params received include:
+  * `output_path`: where to store automated assessment results
+  * `submission`: the path to the submission zip file or folder
+  * `assessment`: the path to the submission assessment resources
+  * `timestamp`: the time of the submission
+  * `task_id`: the task associated with the submission
+  * `overseer_assessment_id`: the overseer assessment id
+  * `docker_image_name_tag`: the tag of the docker image to run the scripts within
+* Overseer starts by unpacking the submission along with the assessment resources to the working directory. Files in the assessment resources will override those in the submission if needed.
+* Once the files are in place Overseer starts a container with the indicated `CONTAINER_NAME` using the image details from the assessment resources and runs two scripts: `build.sh` is run and if the result is 0 it runs `run.sh`.
+  * Anything written to standard output and standard error from these scripts will be collected in the output message for the task.
+  * Each of these scripts is passed a path to a yaml file where comment and status changes are stored.
+  * `build.sh` should write messages to the `build_message` key in the yaml file.
+  * `run.sh` should write messages to the `run_message` key in the yaml file.
+  * Both build and run scripts can write a new status to `new_status`.
+  * The exit status of the build and run steps is appended to the output text collected from standard out.
+* When both scripts have been run, a message is returned to Doubtfire/OnTrack using the `overseer.result` routing key to the `q.overseer` of the `ontrack` exchange. This contains the task id, timestamp, and overseer assessment id. The output text and yaml files are also available to OnTrack.