Updated Readme

README.md

@@ -1,6 +1,108 @@
-# WEE - Workflow Enactment Engine
+# DTDesign Backend
 
-This is the WEE (Workflow Enactment Engine) repository. 
+This directory contains a script that is meant to be used with the following drawio plugin:
 
-The default configuration sets up a development server on port 8081.
+https://msdl.uantwerpen.be/git/jexelmans/drawio/src/master/src/main/webapp/myPlugins/dtdesign.js
+
+The plugin uses the backend to:
+ - Store drawio diagrams (in XML format)
+ - Parse drawio diagrams (using the various domain specific parsers included in this project) and convert them to OML
+ - Convert generated OML files to OWL/RDF (by invoking `gradle`) and load them into a running Fuseki instance.
+
+## Dependencies
+
+On top of the dependencies listed in this repo's main [README](../README.md), you also need:
+
+  - Python packages
+    - drawio2oml
+      - (see parent directory)
+    - xopp2py (Xournal++ to Python to OML converter)
+      - https://msdl.uantwerpen.be/git/jexelmans/xopp2py
+    - Flask (HTTP web server)
+      - https://pypi.org/project/Flask/
+    - Flask-Cors (Flask extension to easily set all HTTP response headers to allow CORS)
+      - https://pypi.org/project/Flask-Cors/
+  - A local clone of this OML project directory:
+    - https://msdl.uantwerpen.be/git/lucasalbertins/DTDesign/src/joeri/examples/oml/SystemDesignOntology2Layers
+    - We'll refer to the path of your local clone as `PATH/TO/SDO2L`.
+  - Gradle (the command `gradle` will be invoked by the backend script, so it needs to be in your PATH)
+    - https://gradle.org/
+
+When building the backend (or the service monitor, see below) with Nix, all dependencies are taken care of automatically. The complete dependency graph of the service monitor (and hence, the Docker container), can be observed in [dependencies.svg](./dependencies.svg).
+
+## Running
+
+There are three ways to run the backend:
+ - Running the backend script manually (recommended for development, for non-Nix users)
+ - Using the service monitor script (recommended for Nix users)
+ - Using the Docker container (recommended if you are only interested in using the application)
+
+### Running the backend script manually
+
+In order to run the backend script directly, there are some prerequesites:
+ 1. Make sure Fuseki is running (run `gradle startFuseki` in `PATH/TO/SDO2L`)
+ 2. Simply invoke `dtdesign-backend PATH/TO/SDO2L`
+
+To use the backend, you also need to host a version of the drawio webapp that has the dtdesign-plugin enabled. Any static web server (e.g., Nginx, Lighttpd, Apache, ...), serving the following directory as its root will work:
+
+https://msdl.uantwerpen.be/git/jexelmans/drawio/src/master/src/main/webapp/
+
+### Using the service monitor script
+
+Included in this project is a service monitor script (based on [supervisord](http://supervisord.org/)) that will start, monitor, restart, and cleanly stop the following services:
+
+  - The dtdesign-backend script (TCP port 5000) from this repository 
+  - Fuseki (TCP port 3030)
+  - Lighttpd (TCP port 8700), statically serving drawio with the dtdesign-plugin
+  - Workflow Enactment Engine (WEE) (TCP port 8081)
+
+This allows running the DTDesign demo as if it were a single application.
+
+To use the script:
+
+```
+PROJECTDIR=/PATH/TO/SDO2L nix run .#serviceMonitor
+```
+
+To end the script, hit Ctrl+C in the same terminal and all services will be cleanly shut down.
+
+### Using the Docker container
+
+A Docker container that contains the service monitor script and all its dependencies, as well as a clone of the SystemDesignOntology2Layers OML project.
+
+#### Building
+
+To build the container:
+
+```
+nix build #.dockerContainer
+```
+
+This places a symlink `result` in the current directory, pointing at the created Docker container image file.
+
+#### Pre-built containers
+
+Pre-built containers are regularly uploaded in this directory:
+
+https://msdl.uantwerpen.be/cloud/public/dfbe22
+
+Just download the latest container version there.
+
+#### Running
+
+To run the container, load the container image, then create and start an instance:
+
+```
+docker load < container.tar.gz # load the image
+docker run -p "8081:8081" -p "5000:5000" -p "3030:3030" -p "8700:8700" # create and start an instance - replace XXX by the hash printed by the previous command
+```
+
+## Using the backend
+
+Once the backend, Fuseki and drawio web server are running, navigate to the following URL:
+
+http://localhost:8700/?p=ftgpm;dtdesign&dev=1&stealth=1
+
+this is an exemple how to run the back-end: python dtdesign-backend drawio/src/main/webapp/myPlugins/shape_libs update-oml-project (but in this case you need to consider
+the both projects update-oml-project and drawio are in the same folder)