Merge branch 'github_and_docu' of github.com:RWTH-ACS/clonemap into github_and_docu

README.md

@@ -5,8 +5,7 @@
 cloneMAP is a multi-agent platform (MAP) that is designed to run in a cloud environment based on [Kubernetes](https://kubernetes.io/).
 The aim of this project is to combine the advantages of cloud computing and a distributed computing paradigm such as multi-agent systems.
 
-[![pipeline status](https://git.rwth-aachen.de/acs/public/cloud/mas/clonemap/badges/master/pipeline.svg)](git.rwth-aachen.de/acs/public/cloud/mas/clonemap/commits/master)
-[![Go Report Card](https://goreportcard.com/badge/git.rwth-aachen.de/acs/public/cloud/mas/clonemap)](https://goreportcard.com/report/git.rwth-aachen.de/acs/public/cloud/mas/clonemap)
+[![Go Report Card](https://goreportcard.com/badge/github.com/rwth-acs/clonemap)](https://goreportcard.com/report/github.com/rwth-acs/clonemap)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 

api/ams/openapi.yaml

@@ -89,6 +89,10 @@ paths:
       responses:
         '201':
           description: Created
+          content:
+            application/json:
+              schema:
+                  $ref: '#/components/schemas/MASInfo'
     delete:
       description: delete all MASs
       responses:
@@ -151,6 +155,12 @@ paths:
       responses:
         '201':
           description: Created
+          content:
+            applications/json:
+              schema:
+                type: array
+                items:
+                  type: integer
   /api/clonemap/mas/{masid}/agents/{agentid}:
     parameters:
     - $ref: '#/components/parameters/masID'

deployments/docker/.env

@@ -9,3 +9,5 @@ CLONEMAP_STUB_HOSTNAME=kubestub
 
 CLONEMAP_MODULE_MQTT=true 
 CLONEMAP_MODULE_FRONTEND=true 
+
+CLONEMAP_DOCKER_TAG=latest

deployments/docker/docker-compose.override.yaml

@@ -12,7 +12,7 @@ services:
       - clonemap-net
 
   logger:
-    image: clonemap/logger
+    image: clonemap/logger:${CLONEMAP_DOCKER_TAG}
     environment:
       CLONEMAP_DEPLOYMENT_TYPE: ${CLONEMAP_DEPLOYMENT_TYPE}
       CLONEMAP_LOG_LEVEL: ${CLONEMAP_LOG_LEVEL}
@@ -25,7 +25,7 @@ services:
       - clonemap-net
 
   df:
-    image: clonemap/df
+    image: clonemap/df:${CLONEMAP_DOCKER_TAG}
     environment:
       CLONEMAP_DEPLOYMENT_TYPE: ${CLONEMAP_DEPLOYMENT_TYPE}
       CLONEMAP_LOG_LEVEL: ${CLONEMAP_LOG_LEVEL}
@@ -38,7 +38,7 @@ services:
       - clonemap-net
 
   pnp:
-    image: clonemap/plugnplay
+    image: clonemap/plugnplay:${CLONEMAP_DOCKER_TAG}
     environment:
       CLONEMAP_DEPLOYMENT_TYPE: ${CLONEMAP_DEPLOYMENT_TYPE}
       CLONEMAP_LOG_LEVEL: ${CLONEMAP_LOG_LEVEL}
@@ -50,7 +50,7 @@ services:
       - clonemap-net
 
   fe:
-    image: clonemap/frontend
+    image: clonemap/frontend:${CLONEMAP_DOCKER_TAG}
     environment:
       CLONEMAP_DEPLOYMENT_TYPE: ${CLONEMAP_DEPLOYMENT_TYPE}
       CLONEMAP_LOG_LEVEL: ${CLONEMAP_LOG_LEVEL}

deployments/docker/docker-compose.yaml

@@ -4,7 +4,7 @@ services:
   kubestub: 
     container_name: kubestub
     hostname: kubestub
-    image: clonemap/clonemap_local
+    image: clonemap/clonemap_local:${CLONEMAP_DOCKER_TAG}
     environment:
       CLONEMAP_LOG_LEVEL: ${CLONEMAP_LOG_LEVEL}
     volumes:
@@ -16,7 +16,7 @@ services:
     stop_grace_period: 30s
 
   ams: 
-    image: clonemap/ams
+    image: clonemap/ams:${CLONEMAP_DOCKER_TAG}
     environment:
       CLONEMAP_DEPLOYMENT_TYPE: ${CLONEMAP_DEPLOYMENT_TYPE}
       CLONEMAP_STORAGE_TYPE: ${CLONEMAP_STORAGE_TYPE}

docs/administration_guide.md

@@ -4,7 +4,7 @@ This administration guide provides the knowledge necessary to start, maintain an
 
 ## Local deployment
 
-Although cloneMAP is designed to be executed within a Kubernetes cluster it can also be executed locally.
+Although cloneMAP is designed to be executed on a Kubernetes cluster it can also be executed locally.
 This is ment as an easier way to test your MAS application.
 Note that microservices such as the AMS, DF and Logger cannot be scaled horizontally with this method.
 Moreover, the platform is not fault-tolerant when deployed locally and cannot be spread over several machines.
@@ -71,7 +71,7 @@ Moreover, you can set the log level to either:
 
 The kubestub container is started in foreground mode.
 It will give a message when a new container is started and show *Ready* once all specified modules are started.
-You can terminate cloneMAP terminating the kubestub container.
+You can terminate cloneMAP by terminating the kubestub container.
 In the concole where you started the kubestub container press `ctrl`+`c`.
 This process might take a few seconds since the kubestub container cleans up before terminating.
 That means that all containers started by the kubestub container are terminated.

docs/user_guide.md

@@ -23,14 +23,11 @@ Implement a task function that takes a pointer to an *Agent* object as parameter
 Start the agency using that task function.
 Every started agent will execute this task function as seperate go-routine.
 
-In the base directory of your project create your Go module file `go.mod`
+In the base directory of your project create your Go module file `go.mod` and add clonemap as dependency
 
-```Go
-module example
-
-require (
-    git.rwth-aachen.de/acs/public/cloud/mas/clonemap v0.0.0-20200109090525-86fd277abf43
-)
+```bash
+go mod init example
+go get github.com/RWTH-ACS/clonemap/pkg/agency@develop
 ```
 
 The following Go code is used for the implementation of the behavior
@@ -76,7 +73,7 @@ The API specification for the agency can be found in [api/agency](../api/agency/
 For interaction with other components, e.g. the DF, you have to implement clients that make use of the corresponding API.
 All REST APIs are specified using the openapi 3 format.
 
-A Python package for the implementation of agents in Python is already available [here](https://git.rwth-aachen.de/acs/public/cloud/mas/cmapy).
+A Python package for the implementation of agents in Python is already available [here](https://github.com/RWTH-ACS/clonemapy).
 
 ### Step 2 Building the Docker image
 
@@ -121,10 +118,14 @@ Create the file `scenario.json` with following content.
     "config":{
         "name":"test",
         "agentsperagency":1,
-        "logging":true,
-        "mqtt":true,
-        "df":false,
-        "log":{
+        "mqtt":{
+            "active":true
+        },
+        "df":{
+            "active":true
+        },
+        "logger":{
+            "active":true,
             "msg":true,
             "app":true,
             "status":true,

pkg/ams/ams.go

@@ -264,11 +264,10 @@ func (ams *AMS) getAgencyInfoFull(masID int, imID int, agencyID int) (ret schema
 }
 
 // createMAS creates a new mas according to masconfig
-func (ams *AMS) createMAS(masSpec schemas.MASSpec) (err error) {
+func (ams *AMS) createMAS(masSpec schemas.MASSpec) (ret schemas.MASInfo, err error) {
 	// fill masInfo
-	var masInfo schemas.MASInfo
 	var numAgencies []int
-	masInfo, numAgencies, err = ams.configureMAS(masSpec)
+	ret, numAgencies, err = ams.configureMAS(masSpec)
 	if err != nil {
 		return
 	}
@@ -280,8 +279,9 @@ func (ams *AMS) createMAS(masSpec schemas.MASSpec) (err error) {
 	if err != nil {
 		return
 	}
+	ret.ID = masID
 
-	go ams.startMAS(masID, masInfo, numAgencies)
+	go ams.startMAS(masID, ret, numAgencies)
 
 	return
 }
@@ -465,8 +465,10 @@ func (ams *AMS) removeMAS(masID int) (err error) {
 	return
 }
 
-// createAgents creates new agents and adds them to an existing mas
-func (ams *AMS) createAgents(masID int, groupSpecs []schemas.ImageGroupSpec) (err error) {
+// createAgents creates new agents and adds them to an existing mas; returns slice with new
+// agent ids
+func (ams *AMS) createAgents(masID int, groupSpecs []schemas.ImageGroupSpec) (ret []int,
+	err error) {
 	for i := range groupSpecs {
 		var newGroup bool
 		var imID int
@@ -484,6 +486,7 @@ func (ams *AMS) createAgents(masID int, groupSpecs []schemas.ImageGroupSpec) (er
 			if err != nil {
 				return
 			}
+			ret = append(ret, agentID)
 			if newGroup {
 				// continue if group is new group
 				continue

pkg/ams/handler.go

@@ -124,13 +124,14 @@ func (ams *AMS) handlePostMAS(w http.ResponseWriter, r *http.Request) {
 		ams.logErrors(r.URL.Path, cmapErr, httpErr)
 		return
 	}
-	cmapErr = ams.createMAS(masSpec)
+	var masInfo schemas.MASInfo
+	masInfo, cmapErr = ams.createMAS(masSpec)
 	if cmapErr != nil {
 		httpErr = httpreply.CMAPError(w, cmapErr.Error())
 		ams.logErrors(r.URL.Path, cmapErr, httpErr)
 		return
 	}
-	httpErr = httpreply.Created(w, cmapErr, "text/plain", []byte("Ressource Created"))
+	httpErr = httpreply.CreatedResource(w, masInfo, cmapErr)
 	ams.logErrors(r.URL.Path, cmapErr, httpErr)
 }
 
@@ -241,13 +242,14 @@ func (ams *AMS) handlePostAgent(w http.ResponseWriter, r *http.Request) {
 		ams.logErrors(r.URL.Path, cmapErr, httpErr)
 		return
 	}
-	cmapErr = ams.createAgents(masID, imgroupSpecs)
+	var agentIDs []int
+	agentIDs, cmapErr = ams.createAgents(masID, imgroupSpecs)
 	if cmapErr != nil {
 		httpErr = httpreply.CMAPError(w, cmapErr.Error())
 		ams.logErrors(r.URL.Path, cmapErr, httpErr)
 		return
 	}
-	httpErr = httpreply.Created(w, cmapErr, "text/plain", []byte("Ressource Created"))
+	httpErr = httpreply.CreatedResource(w, agentIDs, cmapErr)
 	ams.logErrors(r.URL.Path, cmapErr, httpErr)
 }
 

pkg/common/httpreply/httpreply.go

@@ -70,6 +70,25 @@ func Created(w http.ResponseWriter, cmaperr error, content string, answer []byte
 	return
 }
 
+// CreatedResource returns resource after creation
+func CreatedResource(w http.ResponseWriter, v interface{}, cmaperr error) (err error) {
+	if cmaperr == nil {
+		var res []byte
+		res, err = json.Marshal(v)
+		if err == nil {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusCreated)
+			_, err = w.Write(res)
+		} else {
+			err = JSONMarshalError(w)
+		}
+	} else {
+		err = CMAPError(w, cmaperr.Error())
+	}
+
+	return
+}
+
 // Deleted writes standard response for ressource deleteion
 func Deleted(w http.ResponseWriter, cmaperr error) (err error) {
 	if cmaperr == nil {