diff options
| -rw-r--r-- | .env | 22 | ||||
| -rw-r--r-- | README.md | 196 | ||||
| -rw-r--r-- | docker-compose-dev.yml | 17 | ||||
| -rw-r--r-- | docker-compose/.env | 22 | ||||
| -rw-r--r-- | docker-compose/cassandra.yml | 5 | ||||
| -rw-r--r-- | docker-compose/debug.yml | 17 | ||||
| -rw-r--r-- | docker-compose/docker-compose.yml (renamed from docker-compose.yml) | 6 |
7 files changed, 190 insertions, 95 deletions
@@ -1,22 +0,0 @@ -IMAGE_TAG=latest -REGISTRY=nexus3.onap.org:10001/ -JAVA_OPTIONS=-Xmx1536m -Xms1536m -#CS_HOST is set to a dummy string "yyy". This pattern will be used as an identifier to be replaced by the actual -# cassandra host env ip at runtime -CS_HOST=yyy -CS_AUTHENTICATE=false -CS_USER= -CS_PASSWORD= - -WORKFLOW_CASSANDRA_INIT_PORT=9160 -WORKFLOW_BACKEND_CASSANDRA_PORT=9042 -WORKFLOW_BACKEND_DEBUG_PORT=7001 - -#SDC_HOST is set to a dummy string "yyy". This pattern will be used as an identifier to be replaced by the actual SDC -# host env ip at runtime -SDC_HOST=yyy -SDC_PROTOCOL=HTTP -SDC_USER=workflow -SDC_PASSWORD=Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U -WORKFLOW_FRONTEND_PORT=8184 -WORKFLOW_FRONTEND_DEBUG_PORT=7000
\ No newline at end of file @@ -1,8 +1,8 @@ Introduction ============ -Workflow Designer is a [pluggable SDC designer](https://wiki.onap.org/display/DW/Generic+Designer+Support) that allows -a user to design a workflow, save it, and attach it to a SDC service as an artifact. Workflow Designer also manages +Workflow Designer is a [pluggable SDC designer](https://wiki.onap.org/display/DW/Generic+Designer+Support) that allows +a user to design a workflow, save it, and attach it to a SDC service as an artifact. Workflow Designer also manages the definitions of activities, which can be later used as parts of the designed workflows. Components @@ -13,20 +13,22 @@ The designer is comprised of the following deployment units: - Designer backend is the core component. It exposes RESTful APIs for managing workflow and activity data. The backend is agnostic to the type of a workflow artifact — its main concerns are workflow inputs and outputs, and metadata. One of the APIs enables to attach a certified workflow artifact to a SDC service, therefore the designer must be able -to call an API on SDC. In order to do so, the location of a SDC server, and +to call an API on SDC. In order to do so, the location of a SDC server, and [SDC consumer](https://wiki.onap.org/display/DW/Consumer+creation) credentials are required. - -- Designer frontend serves static content of a Web application for creating and managing workflows, and forwards API -requests to the backend. The static content includes JavaScript, images, CSS, etc. A major part of the Web application -is Workflow Composition View — a graphical interface for arranging a workflow sequence. The Web application also produces a -workflow artifact that will be sent to the backend, saved along with other data, and later used by a service. The architecture -allows for different implementations of the frontend component. For example, a different technology can be used for the -Composition View, which will probably also result in a different type of the artifacts (e.g. Bpmn.io vs. Camunda). - -- Cassandra database is used by the designer backend as the main storage for workflow data. A dedicated instance of + +- Designer frontend serves static content of a Web application for creating and managing workflows, and forwards API +requests to the backend. The static content includes JavaScript, images, CSS, etc. A major part of the Web application +is Workflow Composition View — a graphical interface for arranging a workflow sequence. The Web application also +produces a workflow artifact that will be sent to the backend, saved along with other data, and later used by a +service. The architecture allows for different implementations of the frontend component. For example, a different +technology can be used for the Composition View, which will probably also result in a different type of the artifacts +(e.g. Bpmn.io vs. Camunda). + +- Cassandra database is used by the designer backend as the main storage for workflow data. A dedicated instance of Cassandra can be deployed, or an existing cluster may be used. -- Database initialization scripts run once per deployment to create the necessary Cassandra keyspaces and tables, pre-populate data, etc. +- Database initialization scripts run once per deployment to create the necessary Cassandra keyspaces and tables, +pre-populate data, etc. Deployment on Docker ==================== @@ -36,19 +38,19 @@ The procedure below describes manual deployment on plain Docker for development ## 1. Database Create a dedicated instance of Cassandra. This step is optional if you already have a Cassandra cluster. -The designer is not expected to have problems working with Cassandra 3.x, but has been tested with 2.1.x because this is the version used by -SDC. +The designer is not expected to have problems working with Cassandra 3.x, but has been tested with 2.1.x because this +is the version used by SDC. -An easy way to spin up a Cassandra instance is using a Cassandra Docker image as described in the +An easy way to spin up a Cassandra instance is using a Cassandra Docker image as described in the [official documentation](https://hub.docker.com/_/cassandra/). ### Example -`docker run -d --name workflow-cassandra cassandra:2.1` +`docker run -d --name workflow-cassandra cassandra:2.1` ## 2. Database Initialization -**WARNING**: *This step must be executed only once.* +**WARNING**: *This step must be executed only once.* `docker run -ti -e CS_HOST=<cassandra-host> -e CS_PORT=<cassandra-port> -e CS_AUTHENTICATE=true/false -e CS_USER=<cassandra-user> -e CS_PASSWORD=<cassandra-password> nexus3.onap.org:10001/onap/workflow-init:latest` @@ -59,7 +61,7 @@ An easy way to spin up a Cassandra instance is using a Cassandra Docker image as - CS_PORT — Cassandra Thrift client port. If not specified, the default of 9160 will be used. -- CS_AUTHENTICATE — whether password authentication must be used to connect to Cassandra. A *false* will be +- CS_AUTHENTICATE — whether password authentication must be used to connect to Cassandra. A *false* will be assumed if this variable is not specified. - CS_USER — Cassandra username if CS_AUTHENTICATE is *true*. @@ -68,32 +70,33 @@ assumed if this variable is not specified. ### Example -Assuming you have created a dedicated Cassandra container as described in Database section, and the access to it is not +Assuming you have created a dedicated Cassandra container as described in Database section, and the access to it is not protected with a password, the following command will initialize the database: -`docker run -d --name workflow-init --e CS_HOST=$(docker inspect workflow-cassandra --format={{.NetworkSettings.IPAddress}}) +`docker run -d --name workflow-init +-e CS_HOST=$(docker inspect workflow-cassandra --format={{.NetworkSettings.IPAddress}}) nexus3.onap.org:10001/onap/workflow-init:latest` ### Troubleshooting -In order to see if the Workflow Designer was successfully initialized, make sure the console does not contain error messages. -You can also see the logs of the initialization container using `docker logs workflow-init` command. +In order to see if the Workflow Designer was successfully initialized, make sure the console does not contain error +messages. You can also see the logs of the initialization container using `docker logs workflow-init` command. ## 3. Backend -`docker run -d -e SDC_PROTOCL=http/https -e SDC_ENDPOINT=<sdc-host>:<sdc-port> -e SDC_USER=<sdc-username> --e SDC_PASSWORD=<sdc-password> -e CS_HOSTS=<cassandra-hosts> -e CS_PORT=<cassandra-port> --e CS_AUTHENTICATE=true/false -e CS_USER=<cassandra-user> -e CS_PASSWORD=<cassandra-password> +`docker run -d -e SDC_PROTOCL=http/https -e SDC_ENDPOINT=<sdc-host>:<sdc-port> -e SDC_USER=<sdc-username> +-e SDC_PASSWORD=<sdc-password> -e CS_HOSTS=<cassandra-hosts> -e CS_PORT=<cassandra-port> +-e CS_AUTHENTICATE=true/false -e CS_USER=<cassandra-user> -e CS_PASSWORD=<cassandra-password> -e JAVA_OPTIONS=<jvm-options> nexus3.onap.org:10001/onap/workflow-backend:latest` ### Environment Variables - SDC_PROTOCOL — protocol to be used for calling SDC APIs (http or https). -- SDC_ENDPOINT — the base path of SDC external API, in the format `host:port`, where *host* is a SDC backend server, and *port* is usually 8080. +- SDC_ENDPOINT — the base path of SDC external API, in the format `host:port`, where *host* is a SDC backend +server, and *port* is usually 8080. -- SDC_USER — Workflow consumer username +- SDC_USER — Workflow consumer username - SDC_PASSWORD — Workflow consumer password @@ -101,7 +104,7 @@ You can also see the logs of the initialization container using `docker logs wor - CS_PORT — CQL native client port. If not specified, the default of 9042 will be used. -- CS_AUTHENTICATE — whether password authentication must be used to connect to Cassandra. A *false* will be +- CS_AUTHENTICATE — whether password authentication must be used to connect to Cassandra. A *false* will be assumed if this variable is not specified. - CS_USER — Cassandra username if CS_AUTHENTICATE is *true*. @@ -112,23 +115,23 @@ assumed if this variable is not specified. ### Example -Assuming you have a dedicated Cassandra container as described in Database section, and the access to it is not +Assuming you have a dedicated Cassandra container as described in Database section, and the access to it is not protected with a password. The following command will start a backend container: -`docker run -d --name workflow-backend -e SDC_PROTOCOL=http +`docker run -d --name workflow-backend -e SDC_PROTOCOL=http -e SDC_ENDPOINT=$(docker inspect sdc-BE --format={{.NetworkSettings.IPAddress}}):8080 --e CS_HOSTS=$(docker inspect workflow-cassandra --format={{.NetworkSettings.IPAddress}}) +-e CS_HOSTS=$(docker inspect workflow-cassandra --format={{.NetworkSettings.IPAddress}}) -e SDC_USER=workflow -e SDC_PASSWORD=<secret> -e JAVA_OPTIONS="-Xmx128m -Xms128m -Xss1m" nexus3.onap.org:10001/onap/workflow-backend:latest` ### Troubleshooting -In order to verify that the Workflow Designer backend has started successfully, check the logs of the -backend container. For example, by running `docker logs workflow-backend`. The logs must not contain any +In order to verify that the Workflow Designer backend has started successfully, check the logs of the +backend container. For example, by running `docker logs workflow-backend`. The logs must not contain any error messages. -Application logs are located in the */var/log/ONAP/workflow-designer/backend* directory of a workflow backend -container. For example, you can view the audit log by running +Application logs are located in the */var/log/ONAP/workflow-designer/backend* directory of a workflow backend +container. For example, you can view the audit log by running `docker exec -ti workflow-backend less /var/log/ONAP/workflow-designer/backend/audit.log`. ## 4. Frontend @@ -142,32 +145,116 @@ nexus3.onap.org:10001/onap/workflow-frontend:latest` ### Example -`docker run -d --name workflow-frontend --e BACKEND=http://$(docker inspect workflow-backend --format={{.NetworkSettings.IPAddress}}):8080 +`docker run -d --name workflow-frontend +-e BACKEND=http://$(docker inspect workflow-backend --format={{.NetworkSettings.IPAddress}}):8080 -e JAVA_OPTIONS="-Xmx64m -Xms64m -Xss1m" -p 9088:8080 nexus3.onap.org:10001/onap/workflow-frontend:latest` -Notice that port 8080 of the frontend container has been -[mapped]( https://docs.docker.com/config/containers/container-networking/#published-ports) to port 9088 of the host -machine. This makes the Workflow Designer Web application accessible from the outside world via the host machine's +Notice that port 8080 of the frontend container has been +[mapped]( https://docs.docker.com/config/containers/container-networking/#published-ports) to port 9088 of the host +machine. This makes the Workflow Designer Web application accessible from the outside world via the host machine's IP address/hostname. ### Troubleshooting -In order to check if the Workflow Designer frontend has successfully started, look at the logs of the -frontend container. For example, by running `docker logs workflow-frontend`. The logs should not contain +In order to check if the Workflow Designer frontend has successfully started, look at the logs of the +frontend container. For example, by running `docker logs workflow-frontend`. The logs should not contain error messages. Workflow frontend does not have backend logic, therefore there are no application logs. +Deployment Using Docker Compose +=============================== + +[Docker Compose](https://docs.docker.com/compose/) further simplifies the deployment of Workflow Designer. +The Docker Compose files can be find in the workflow designer Git repository, under _docker-compose_ directory. + +> In order to use this deployment method, you need to install Docker Compose as described on +[Install Docker Compose](https://docs.docker.com/compose/install/) official page. + +## 1. Cassandra Database + +Instantiation of a Cassandra database is not part of the the Docker Compose service. You may already have a running +instance of Cassandra you want to use. It can be in a Docker container, on a VM, or a physical machine. + +If you want to spin up a Cassandra database alongside the Workflow Designer service for development purposes, +use the following command: + +`docker-compose -p workflow -f cassandra.yml up -d` + +> Note, that since the database was created under the same project (`-p workflow`), but as a separate service, it will +keep running when you shut down the workflow designer service. This will cause an error message +_ERROR: network workflow_default id <......> has active endpoints_. + +## 2. Environment Variables + +Edit _.env_ file located in _docker-compose_ directory. Here is a brief overview of some variables. + +- IMAGE_TAG — enables to try other versions of the Docker images + +- REGISTRY — allows to use any Docker registry; leave it blank for locally built images + +- CS_HOST — Cassandra host name or IP address. Keep in mind that the host must be accessible from the +[Docker Compose network](https://docs.docker.com/compose/networking/) created for the workflow service. +Use `CS_HOST=cassandra` if you created the database as described in the previous section. + +- SDC_HOST — usually, IP address of the Docker host (if you are using the SDC deploy script). + +- CASSANDRA_INIT_PORT — Cassandra Thrift port, usually 9160. + +- CASSANDRA_PORT — Cassandra CQL native client port, usually 9042. + +- BACKEND_DEBUG_PORT — *host* port used to debug the backend server (see below). + +- FRONTEND_DEBUG_PORT — *host* port used to debug the frontend server (see below). + +- FRONTEND_PORT — *host* port Workflow Designer UI will be accessible at. + +> Other variables are described in _Deployment on Docker_ section. + +## 3. Starting Workflow Designer Service + +Assuming the database is up and running, execute the following in the command line: + +`docker-compose -p workflow up -d`. + +It is easy to restart or recreate the entire service or a selected component using Docker Compose commands, for example +to pick up new versions of the Docker images. Keep in mind that the database may remain unchanged, so that the new +service will continue to work with old data. + +For example, you can restart just the frontend by issuing the command: + +`docker-compose -p workflow restart workflow-frontend` + +Keep in mind that changes to the _docker-compose.yml_ configuration or environment variables +[will not be reflected](https://docs.docker.com/compose/reference/restart/) when using `restart`. For that, you will +need to recreate the container (e.g. to change the image version): + +`docker-compose -p workflow up -d --no-deps workflow-frontend` + +For more advanced features and commands, please refer to +[Docker Compose documentation](https://docs.docker.com/compose/). + +## 4. Stopping Workflow Designer Service + +You can shut down the entire stack of Workflow Designer components using +`docker-compose -p workflow down`. + +## 5. Starting Workflow Designer in Debug Mode + +It is possible to start the service in debug mode, when both the front-end and the back-end are accessible from a +remote debugger at mapped host ports. Run: + +`docker-compose -p workflow -f docker-compose.yml -f debug.yml up -d`. + SDC Plugin Configuration ======================== In order to run as an SDC pluggable designer, Workflow Designer must be added to SDC configuration as described in -[Generic plugin support](https://wiki.onap.org/display/DW/Generic+Designer+Support). +[Generic plugin support](https://wiki.onap.org/display/DW/Generic+Designer+Support). -If you are deploying SDC using a standard procedure (OOM or the -[SDC shell script](https://wiki.onap.org/display/DW/Deploying+SDC+on+a+Linux+VM+for+Development)), -the easiest way to configure the Workflow plugin is to edit the *default_attributes/Plugins/WORKFLOW* +If you are deploying SDC using a standard procedure (OOM or the +[SDC shell script](https://wiki.onap.org/display/DW/Deploying+SDC+on+a+Linux+VM+for+Development)), +the easiest way to configure the Workflow plugin is to edit the *default_attributes/Plugins/WORKFLOW* section of *AUTO.json*. ### Plugin Source @@ -175,19 +262,19 @@ section of *AUTO.json*. The main endpoint to load Workflow Designer Web application is defined by `"pluginSourceUrl": "http://<host>:<port>"`. Keep in mind that the URL **must be accessible from a user's browser**. In most cases, `<host>` will be the hostname or -IP address of the machine that runs Docker engine, and `<port>` will be a host port to which you have published port +IP address of the machine that runs Docker engine, and `<port>` will be a host port to which you have published port 8080 of the Workflow frontend container. ### Plugin Discovery -In order to check the availability of a plugin, SDC uses `"pluginDiscoveryUrl"`. For Workflow the value is +In order to check the availability of a plugin, SDC uses `"pluginDiscoveryUrl"`. For Workflow the value is `http://<host>:<port>/ping`. ### Example -Let's assume that hostname of the machine that runs Docker containers with the Workflow application is -*workflow.example.com*, and port 8080 of the Workflow frontend is mapped to 9088 on the host. In this case the corresponding -section of *AUTO.json* will look like below: +Let's assume that hostname of the machine that runs Docker containers with the Workflow application is +*workflow.example.com*, and port 8080 of the Workflow frontend is mapped to 9088 on the host. In this case the +corresponding section of *AUTO.json* will look like below: ``` @@ -199,3 +286,6 @@ section of *AUTO.json* will look like below: }, ``` + +In a development or demo environment, Workflow Designer will run on the same host as SDC, so that its IP address will +be the one of the Docker host.
\ No newline at end of file diff --git a/docker-compose-dev.yml b/docker-compose-dev.yml deleted file mode 100644 index 44c8d48d..00000000 --- a/docker-compose-dev.yml +++ /dev/null @@ -1,17 +0,0 @@ -version: '3' -services: - - #Added Debug configurations - Exposing port and added required JAVA_OPTIONS for debug - # for both backend and frontend - - workflow-backend: - ports: - - "${WORKFLOW_BACKEND_DEBUG_PORT}:${WORKFLOW_BACKEND_DEBUG_PORT}" - environment: - - JAVA_OPTIONS=${JAVA_OPTIONS} -Xdebug -agentlib:jdwp=transport=dt_socket,address=${WORKFLOW_BACKEND_DEBUG_PORT},server=y,suspend=n - - workflow-frontend: - ports: - - "${WORKFLOW_FRONTEND_DEBUG_PORT}:${WORKFLOW_FRONTEND_DEBUG_PORT}" - environment: - - JAVA_OPTIONS=${JAVA_OPTIONS} -Xdebug -agentlib:jdwp=transport=dt_socket,address=${WORKFLOW_FRONTEND_DEBUG_PORT},server=y,suspend=n
\ No newline at end of file diff --git a/docker-compose/.env b/docker-compose/.env new file mode 100644 index 00000000..58f6cb30 --- /dev/null +++ b/docker-compose/.env @@ -0,0 +1,22 @@ +IMAGE_TAG=latest +REGISTRY=nexus3.onap.org:10001/ +JAVA_OPTIONS=-Xmx1536m -Xms1536m +# CS_HOST is set to a dummy string "yyy". This pattern will be used as an identifier to be replaced by the actual +# Cassandra hostname or IP address at runtime +CS_HOST=yyy +CS_AUTHENTICATE=false +CS_USER= +CS_PASSWORD= + +CASSANDRA_INIT_PORT=9160 +CASSANDRA_PORT=9042 +BACKEND_DEBUG_PORT=7001 + +# SDC_HOST is set to a dummy string "yyy". This pattern will be used as an identifier to be replaced by the actual SDC +# hostname or IP address at runtime +SDC_HOST=yyy +SDC_PROTOCOL=HTTP +SDC_USER=workflow +SDC_PASSWORD=Kp8bJ4SXszM0WXlhak3eHlcse2gAw84vaoGGmJvUy2U +FRONTEND_PORT=8184 +FRONTEND_DEBUG_PORT=7000
\ No newline at end of file diff --git a/docker-compose/cassandra.yml b/docker-compose/cassandra.yml new file mode 100644 index 00000000..251b4c99 --- /dev/null +++ b/docker-compose/cassandra.yml @@ -0,0 +1,5 @@ +version: '3' +services: + + cassandra: + image: "cassandra:2.1" diff --git a/docker-compose/debug.yml b/docker-compose/debug.yml new file mode 100644 index 00000000..de0873f1 --- /dev/null +++ b/docker-compose/debug.yml @@ -0,0 +1,17 @@ +version: '3' +services: + + # Added debug configurations - exposing port and added required JAVA_OPTIONS for debug + # for both backend and frontend + + workflow-backend: + ports: + - "${BACKEND_DEBUG_PORT}:${BACKEND_DEBUG_PORT}" + environment: + - JAVA_OPTIONS=${JAVA_OPTIONS} -Xdebug -agentlib:jdwp=transport=dt_socket,address=${BACKEND_DEBUG_PORT},server=y,suspend=n + + workflow-frontend: + ports: + - "${FRONTEND_DEBUG_PORT}:${FRONTEND_DEBUG_PORT}" + environment: + - JAVA_OPTIONS=${JAVA_OPTIONS} -Xdebug -agentlib:jdwp=transport=dt_socket,address=${FRONTEND_DEBUG_PORT},server=y,suspend=n
\ No newline at end of file diff --git a/docker-compose.yml b/docker-compose/docker-compose.yml index ec1bd4b5..daadff0e 100644 --- a/docker-compose.yml +++ b/docker-compose/docker-compose.yml @@ -8,7 +8,7 @@ services: - CS_AUTHENTICATE - CS_USER - CS_PASSWORD - - CS_PORT=${WORKFLOW_CASSANDRA_INIT_PORT} + - CS_PORT=${CASSANDRA_INIT_PORT} workflow-backend: depends_on: @@ -19,7 +19,7 @@ services: - CS_HOSTS=${CS_HOST} - CS_USER - CS_PASSWORD - - CS_PORT=${WORKFLOW_BACKEND_CASSANDRA_PORT} + - CS_PORT=${CASSANDRA_PORT} - SDC_PROTOCOL - SDC_ENDPOINT="${SDC_HOST}:8080" - SDC_USER @@ -31,7 +31,7 @@ services: - workflow-backend image: "${REGISTRY}onap/workflow-frontend:${IMAGE_TAG}" ports: - - "${WORKFLOW_FRONTEND_PORT}:8080" + - "${FRONTEND_PORT}:8080" environment: - JAVA_OPTIONS - BACKEND=http://workflow-backend:8080 |