4 Workflow Designer is a [pluggable SDC designer](https://wiki.onap.org/display/DW/Generic+Designer+Support) that allows
5 a user to design a workflow, save it, and attach it to a SDC service as an artifact. Workflow Designer also manages
6 the definitions of activities, which can be later used as parts of the designed workflows.
11 The designer is comprised of the following deployment units:
13 - Designer backend is the core component. It exposes RESTful APIs for managing workflow and activity data. The backend
14 is agnostic to the type of a workflow artifact — its main concerns are workflow inputs and outputs, and metadata.
15 One of the APIs enables to attach a certified workflow artifact to a SDC service, therefore the designer must be able
16 to call an API on SDC. In order to do so, the location of a SDC server, and
17 [SDC consumer](https://wiki.onap.org/display/DW/Consumer+creation) credentials are required.
19 - Designer frontend serves static content of a Web application for creating and managing workflows, and forwards API
20 requests to the backend. The static content includes JavaScript, images, CSS, etc. A major part of the Web application
21 is Workflow Composition View — a graphical interface for arranging a workflow sequence. The Web application also
22 produces a workflow artifact that will be sent to the backend, saved along with other data, and later used by a
23 service. The architecture allows for different implementations of the frontend component. For example, a different
24 technology can be used for the Composition View, which will probably also result in a different type of the artifacts
25 (e.g. Bpmn.io vs. Camunda).
27 - Cassandra database is used by the designer backend as the main storage for workflow data. A dedicated instance of
28 Cassandra can be deployed, or an existing cluster may be used.
30 - Database initialization scripts run once per deployment to create the necessary Cassandra keyspaces and tables,
31 pre-populate data, etc.
36 The procedure below describes manual deployment on plain Docker for development or a demo.
40 Create a dedicated instance of Cassandra. This step is optional if you already have a Cassandra cluster.
41 The designer is not expected to have problems working with Cassandra 3.x, but has been tested with 2.1.x because this
42 is the version used by SDC.
44 An easy way to spin up a Cassandra instance is using a Cassandra Docker image as described in the
45 [official documentation](https://hub.docker.com/_/cassandra/).
49 `docker run -d --name workflow-cassandra cassandra:2.1`
51 ## 2. Database Initialization
53 **WARNING**: *This step must be executed only once.*
55 `docker run -ti -e CS_HOST=<cassandra-host> -e CS_PORT=<cassandra-port> -e CS_AUTHENTICATE=true/false
56 -e CS_USER=<cassandra-user> -e CS_PASSWORD=<cassandra-password> nexus3.onap.org:10001/onap/workflow-init:latest`
58 ### Environment Variables
60 - CS_HOST — Cassandra hostname or IP address.
62 - CS_PORT — Cassandra Thrift client port. If not specified, the default of 9160 will be used.
64 - CS_AUTHENTICATE — whether password authentication must be used to connect to Cassandra. A *false* will be
65 assumed if this variable is not specified.
67 - CS_USER — Cassandra username if CS_AUTHENTICATE is *true*.
69 - CS_PASSWORD — Cassandra password if CS_AUTHENTICATE is *true*.
73 Assuming you have created a dedicated Cassandra container as described in Database section, and the access to it is not
74 protected with a password, the following command will initialize the database:
76 `docker run -d --name workflow-init
77 -e CS_HOST=$(docker inspect workflow-cassandra --format={{.NetworkSettings.IPAddress}})
78 nexus3.onap.org:10001/onap/workflow-init:latest`
82 In order to see if the Workflow Designer was successfully initialized, make sure the console does not contain error
83 messages. You can also see the logs of the initialization container using `docker logs workflow-init` command.
87 `docker run -d -e SDC_PROTOCL=http/https -e SDC_ENDPOINT=<sdc-host>:<sdc-port> -e SDC_USER=<sdc-username>
88 -e SDC_PASSWORD=<sdc-password> -e CS_HOSTS=<cassandra-hosts> -e CS_PORT=<cassandra-port>
89 -e CS_AUTHENTICATE=true/false -e CS_USER=<cassandra-user> -e CS_PASSWORD=<cassandra-password>
90 -e JAVA_OPTIONS=<jvm-options> nexus3.onap.org:10001/onap/workflow-backend:latest`
92 ### Environment Variables
94 - SDC_PROTOCOL — protocol to be used for calling SDC APIs (http or https).
96 - SDC_ENDPOINT — the base path of SDC external API, in the format `host:port`, where *host* is a SDC backend
97 server, and *port* is usually 8080.
99 - SDC_USER — Workflow consumer username
101 - SDC_PASSWORD — Workflow consumer password
103 - CS_HOSTS — comma-separated list of Cassandra hostnames or IP addresses.
105 - CS_PORT — CQL native client port. If not specified, the default of 9042 will be used.
107 - CS_AUTHENTICATE — whether password authentication must be used to connect to Cassandra. A *false* will be
108 assumed if this variable is not specified.
110 - CS_USER — Cassandra username if CS_AUTHENTICATE is *true*.
112 - CS_PASSWORD — Cassandra password if CS_AUTHENTICATE is *true*.
114 - JAVA_OPTIONS — optionally, JVM (Java Virtual Machine) arguments.
118 Assuming you have a dedicated Cassandra container as described in Database section, and the access to it is not
119 protected with a password. The following command will start a backend container:
121 `docker run -d --name workflow-backend -e SDC_PROTOCOL=http
122 -e SDC_ENDPOINT=$(docker inspect sdc-BE --format={{.NetworkSettings.IPAddress}}):8080
123 -e CS_HOSTS=$(docker inspect workflow-cassandra --format={{.NetworkSettings.IPAddress}})
124 -e SDC_USER=workflow -e SDC_PASSWORD=<secret> -e JAVA_OPTIONS="-Xmx128m -Xms128m -Xss1m"
125 nexus3.onap.org:10001/onap/workflow-backend:latest`
129 In order to verify that the Workflow Designer backend has started successfully, check the logs of the
130 backend container. For example, by running `docker logs workflow-backend`. The logs must not contain any
133 Application logs are located in the */var/log/ONAP/workflow-designer/backend* directory of a workflow backend
134 container. For example, you can view the audit log by running
135 `docker exec -ti workflow-backend less /var/log/ONAP/workflow-designer/backend/audit.log`.
139 `docker run -d -e BACKEND=http://<backend-host>:<backend-port> -e JAVA_OPTIONS=<jvm-options>
140 nexus3.onap.org:10001/onap/workflow-frontend:latest`
142 - BACKEND — root endpoint of the RESTful APIs exposed by a workflow backend server.
144 - JAVA_OPTIONS — optionally, JVM (Java Virtual Machine) arguments.
148 `docker run -d --name workflow-frontend
149 -e BACKEND=http://$(docker inspect workflow-backend --format={{.NetworkSettings.IPAddress}}):8080
150 -e JAVA_OPTIONS="-Xmx64m -Xms64m -Xss1m" -p 9088:8080 nexus3.onap.org:10001/onap/workflow-frontend:latest`
152 Notice that port 8080 of the frontend container has been
153 [mapped]( https://docs.docker.com/config/containers/container-networking/#published-ports) to port 9088 of the host
154 machine. This makes the Workflow Designer Web application accessible from the outside world via the host machine's
159 In order to check if the Workflow Designer frontend has successfully started, look at the logs of the
160 frontend container. For example, by running `docker logs workflow-frontend`. The logs should not contain
163 Workflow frontend does not have backend logic, therefore there are no application logs.
165 Deployment Using Docker Compose
166 ===============================
168 [Docker Compose](https://docs.docker.com/compose/) further simplifies the deployment of Workflow Designer.
169 The Docker Compose files can be find in the workflow designer Git repository, under _docker-compose_ directory.
171 > In order to use this deployment method, you need to install Docker Compose as described on
172 [Install Docker Compose](https://docs.docker.com/compose/install/) official page.
174 ## 1. Cassandra Database
176 Instantiation of a Cassandra database is not part of the the Docker Compose service. You may already have a running
177 instance of Cassandra you want to use. It can be in a Docker container, on a VM, or a physical machine.
179 If you want to spin up a Cassandra database alongside the Workflow Designer service for development purposes,
180 use the following command:
182 `docker-compose -p workflow -f cassandra.yml up -d`
184 > Note, that since the database was created under the same project (`-p workflow`), but as a separate service, it will
185 keep running when you shut down the workflow designer service. This will cause an error message
186 _ERROR: network workflow_default id <......> has active endpoints_.
188 ## 2. Environment Variables
190 Edit _.env_ file located in _docker-compose_ directory. Here is a brief overview of some variables.
192 - IMAGE_TAG — enables to try other versions of the Docker images
194 - REGISTRY — allows to use any Docker registry; leave it blank for locally built images
196 - CS_HOST — Cassandra host name or IP address. Keep in mind that the host must be accessible from the
197 [Docker Compose network](https://docs.docker.com/compose/networking/) created for the workflow service.
198 Use `CS_HOST=cassandra` if you created the database as described in the previous section.
200 - SDC_HOST — usually, IP address of the Docker host (if you are using the SDC deploy script).
202 - CASSANDRA_INIT_PORT — Cassandra Thrift port, usually 9160.
204 - CASSANDRA_PORT — Cassandra CQL native client port, usually 9042.
206 - BACKEND_DEBUG_PORT — *host* port used to debug the backend server (see below).
208 - FRONTEND_DEBUG_PORT — *host* port used to debug the frontend server (see below).
210 - FRONTEND_PORT — *host* port Workflow Designer UI will be accessible at.
212 > Other variables are described in _Deployment on Docker_ section.
214 ## 3. Starting Workflow Designer Service
216 Assuming the database is up and running, execute the following in the command line:
218 `docker-compose -p workflow up -d`.
220 It is easy to restart or recreate the entire service or a selected component using Docker Compose commands, for example
221 to pick up new versions of the Docker images. Keep in mind that the database may remain unchanged, so that the new
222 service will continue to work with old data.
224 For example, you can restart just the frontend by issuing the command:
226 `docker-compose -p workflow restart workflow-frontend`
228 Keep in mind that changes to the _docker-compose.yml_ configuration or environment variables
229 [will not be reflected](https://docs.docker.com/compose/reference/restart/) when using `restart`. For that, you will
230 need to recreate the container (e.g. to change the image version):
232 `docker-compose -p workflow up -d --no-deps workflow-frontend`
234 For more advanced features and commands, please refer to
235 [Docker Compose documentation](https://docs.docker.com/compose/).
237 ## 4. Stopping Workflow Designer Service
239 You can shut down the entire stack of Workflow Designer components using
240 `docker-compose -p workflow down`.
242 ## 5. Starting Workflow Designer in Debug Mode
244 It is possible to start the service in debug mode, when both the front-end and the back-end are accessible from a
245 remote debugger at mapped host ports. Run:
247 `docker-compose -p workflow -f docker-compose.yml -f debug.yml up -d`.
249 SDC Plugin Configuration
250 ========================
252 In order to run as an SDC pluggable designer, Workflow Designer must be added to SDC configuration as described in
253 [Generic plugin support](https://wiki.onap.org/display/DW/Generic+Designer+Support).
255 If you are deploying SDC using a standard procedure (OOM or the
256 [SDC shell script](https://wiki.onap.org/display/DW/Deploying+SDC+on+a+Linux+VM+for+Development)),
257 the easiest way to configure the Workflow plugin is to edit the *default_attributes/Plugins/WORKFLOW*
258 section of *AUTO.json*.
262 The main endpoint to load Workflow Designer Web application is defined by `"pluginSourceUrl": "http://<host>:<port>"`.
264 Keep in mind that the URL **must be accessible from a user's browser**. In most cases, `<host>` will be the hostname or
265 IP address of the machine that runs Docker engine, and `<port>` will be a host port to which you have published port
266 8080 of the Workflow frontend container.
270 In order to check the availability of a plugin, SDC uses `"pluginDiscoveryUrl"`. For Workflow the value is
271 `http://<host>:<port>/ping`.
275 Let's assume that hostname of the machine that runs Docker containers with the Workflow application is
276 *workflow.example.com*, and port 8080 of the Workflow frontend is mapped to 9088 on the host. In this case the
277 corresponding section of *AUTO.json* will look like below:
283 "workflow_discovery_url": "http://workflow.example.com:9088/ping",
284 "workflow_source_url": "http://workflow.example.com:9088"
290 In a development or demo environment, Workflow Designer will run on the same host as SDC, so that its IP address will
291 be the one of the Docker host.