README.md

   1 Introduction
   2 ============
   3
   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.
   7
   8 Components
   9 ==========
  10
  11 The designer is comprised of the following deployment units:
  12
  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 &mdash; 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.
  18
  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 &mdash; 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).
  26
  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.
  29
  30 - Database initialization scripts run once per deployment to create the necessary Cassandra keyspaces and tables,
  31 pre-populate data, etc.
  32
  33 Deployment on Docker
  34 ====================
  35
  36 The procedure below describes manual deployment on plain Docker for development or a demo.
  37
  38 ## 1. Database
  39
  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.
  43
  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/).
  46
  47 ### Example
  48
  49 `docker run -d --name workflow-cassandra cassandra:2.1`
  50
  51 ## 2. Database Initialization
  52
  53 **WARNING**: *This step must be executed only once.*
  54
  55 Workflow Designer requires two Cassandra namespaces:
  56
  57 - WORKFLOW
  58 - ZUSAMMEN_WORKFLOW
  59
  60 By default, these keyspaces are configured to use a simple replication strategy (`'class' : 'SimpleStrategy'`)
  61 and the replication factor of one (`'replication_factor' : 1`). In order to override this configuration, override
  62 the *create_keyspaces.cql* file at the root of the initialization container using
  63 [Docker volume mapping](https://docs.docker.com/storage/volumes/). Include `IF NOT EXISTS` clause in the keyspace
  64 creation statements to prevent accidental data loss.
  65
  66 `docker run -ti -e CS_HOST=<cassandra-host> -e CS_PORT=<cassandra-port> -e CS_AUTHENTICATE=true/false
  67 -e CS_USER=<cassandra-user> -e CS_PASSWORD=<cassandra-password> nexus3.onap.org:10001/onap/workflow-init:latest`
  68
  69 ### Environment Variables
  70
  71 - CS_HOST &mdash; Cassandra hostname or IP address.
  72
  73 - CS_PORT &mdash; Cassandra Thrift client port. If not specified, the default of 9160 will be used.
  74
  75 - CS_AUTHENTICATE &mdash; whether password authentication must be used to connect to Cassandra. A *false* will be
  76 assumed if this variable is not specified.
  77
  78 - CS_USER &mdash; Cassandra username if CS_AUTHENTICATE is *true*.
  79
  80 - CS_PASSWORD &mdash; Cassandra password if CS_AUTHENTICATE is *true*.
  81
  82 ### Example
  83
  84 Assuming you have created a dedicated Cassandra container as described in Database section, and the access to it is not
  85 protected with a password, the following command will initialize the database:
  86
  87 `docker run -d --name workflow-init
  88 -e CS_HOST=$(docker inspect workflow-cassandra --format={{.NetworkSettings.IPAddress}})
  89 nexus3.onap.org:10001/onap/workflow-init:latest`
  90
  91 ### Troubleshooting
  92
  93 In order to see if the Workflow Designer was successfully initialized, make sure the console does not contain error
  94 messages. You can also see the logs of the initialization container using `docker logs workflow-init` command.
  95
  96 ## 3. Backend
  97
  98 `docker run -d -e SDC_PROTOCL=http/https -e SDC_ENDPOINT=<sdc-host>:<sdc-port> -e SDC_USER=<sdc-username>
  99 -e SDC_PASSWORD=<sdc-password> -e CS_HOSTS=<cassandra-hosts> -e CS_PORT=<cassandra-port>
 100 -e CS_AUTHENTICATE=true/false -e CS_USER=<cassandra-user> -e CS_PASSWORD=<cassandra-password>
 101 -e CS_SSL_ENABLED=true/false --volume <cassandra-truststore-path_container>:<cassandra-truststore-path_local>
 102 -e CS_TRUST_STORE_PATH=<cassandra-truststore-path_container> -e CS_TRUST_STORE_PASSWORD=<cassandra-truststore-password>
 103 -e SERVER_SSL_ENABLED=true/false -e SERVER_SSL_KEY_PASSWORD=<ssl_key_password>
 104 -e SERVER_SSL_KEYSTORE_PATH=<ssl_keystore_path> -e SERVER_SSL_KEYSTORE_TYPE=<ssl_keystore_type>
 105 -e JAVA_OPTIONS=<jvm-options> nexus3.onap.org:10001/onap/workflow-backend:latest`
 106
 107 ### Environment Variables
 108
 109 - SDC_PROTOCOL &mdash; protocol to be used for calling SDC APIs (http or https).
 110
 111 - SDC_ENDPOINT &mdash; the base path of SDC external API, in the format `host:port`, where *host* is a SDC backend
 112 server, and *port* is usually 8080.
 113
 114 - SDC_USER &mdash; Workflow consumer username
 115
 116 - SDC_PASSWORD &mdash; Workflow consumer password
 117
 118 - CS_HOSTS &mdash; comma-separated list of Cassandra hostnames or IP addresses.
 119
 120 - CS_PORT &mdash; CQL native client port. If not specified, the default of 9042 will be used.
 121
 122 - CS_AUTHENTICATE &mdash; whether password authentication must be used to connect to Cassandra. A *false* will be
 123 assumed if this variable is not specified.
 124
 125 - CS_USER &mdash; Cassandra username if CS_AUTHENTICATE is *true*.
 126
 127 - CS_PASSWORD &mdash; Cassandra password if CS_AUTHENTICATE is *true*.
 128
 129 - CS_SSL_ENABLED &mdash; whether ssl authentication must be used to connect to Cassandra. A *false* will be
 130 assumed if this variable is not specified.
 131
 132 - CS_TRUST_STORE_PATH &mdash; Cassandra Truststore path if CS_SSL_ENABLED is *true*.
 133
 134 - CS_TRUST_STORE_PASSWORD &mdash; Cassandra Truststore password if CS_SSL_ENABLED is *true*.
 135
 136 - SERVER_SSL_ENABLED &mdash; whether ssl authentication must be used to connect to application. A *false* will be
 137 assumed if this variable is not specified.
 138
 139 - SERVER_SSL_KEY_PASSWORD &mdash; SSL key password if SERVER_SSL_ENABLED is *true*.
 140
 141 - SERVER_SSL_KEYSTORE_PATH &mdash; SSL Keystore path if SERVER_SSL_ENABLED is *true*.
 142
 143 - SERVER_SSL_KEYSTORE_TYPE &mdash; SSL Keystore type if SERVER_SSL_ENABLED is *true*.
 144
 145 - JAVA_OPTIONS &mdash; optionally, JVM (Java Virtual Machine) arguments.
 146
 147 ### Example
 148
 149 Assuming you have a dedicated Cassandra container as described in Database section, and the access to it is not
 150 protected with a password. The following command will start a backend container without SSL support:
 151
 152 `docker run -d --name workflow-backend -e SDC_PROTOCOL=http
 153 -e SDC_ENDPOINT=$(docker inspect sdc-BE --format={{.NetworkSettings.IPAddress}}):8080
 154 -e CS_HOSTS=$(docker inspect workflow-cassandra --format={{.NetworkSettings.IPAddress}})
 155 -e SDC_USER=workflow -e SDC_PASSWORD=<secret> -e JAVA_OPTIONS="-Xmx128m -Xms128m -Xss1m"
 156 nexus3.onap.org:10001/onap/workflow-backend:latest`
 157
 158 ### Troubleshooting
 159
 160 In order to verify that the Workflow Designer backend has started successfully, check the logs of the
 161 backend container. For example, by running `docker logs workflow-backend`. The logs must not contain any
 162 error messages.
 163
 164 Application logs are located in the */var/log/ONAP/workflow-designer/backend* directory of a workflow backend
 165 container. For example, you can view the audit log by running
 166 `docker exec -ti workflow-backend less /var/log/ONAP/workflow-designer/backend/audit.log`.
 167
 168 ## 4. Frontend
 169
 170 `docker run -d -e BACKEND=http://<backend-host>:<backend-port> -e JAVA_OPTIONS=<jvm-options>
 171 nexus3.onap.org:10001/onap/workflow-frontend:latest`
 172
 173 - BACKEND &mdash; root endpoint of the RESTful APIs exposed by a workflow backend server.
 174
 175 - JAVA_OPTIONS &mdash; optionally, JVM (Java Virtual Machine) arguments.
 176
 177 For SSL connectivity:
 178
 179 - IS_HTTPS &mdash; flag to set if frontend accepts https connection from client. Default is false.
 180
 181 - KEYSTORE_PATH
 182 - KEYSTORE_PASSWORD
 183 - KEYSTORE_TYPE
 184 - TRUSTSTORE_PATH
 185 - TRUSTSTORE_PASSWORD
 186 - TRUSTSTORE_TYPE
 187
 188 If not set then Using jetty default SSL keys.
 189
 190 ### Example
 191
 192 `docker run -d --name workflow-frontend
 193 -e BACKEND=http://$(docker inspect workflow-backend --format={{.NetworkSettings.IPAddress}}):8080
 194 -e JAVA_OPTIONS="-Xmx64m -Xms64m -Xss1m" -p 9088:8080 -p 8186:8443 -e IS_HTTPS=true nexus3.onap.org:10001/onap/workflow-frontend:latest`
 195
 196 Notice that port 8080 of the frontend container has been
 197 [mapped]( https://docs.docker.com/config/containers/container-networking/#published-ports) to port 9088 of the host
 198 machine. This makes the Workflow Designer Web application accessible from the outside world via the host machine's
 199 IP address/hostname.
 200
 201 To expose the https port 8443 of the container we have published in the example 8186.
 202 ### Troubleshooting
 203
 204 In order to check if the Workflow Designer frontend has successfully started, look at the logs of the
 205 frontend container. For example, by running `docker logs workflow-frontend`. The logs should not contain
 206 error messages.
 207
 208 Workflow frontend does not have backend logic, therefore there are no application logs.
 209
 210 Deployment Using Docker Compose
 211 ===============================
 212
 213 [Docker Compose](https://docs.docker.com/compose/) further simplifies the deployment of Workflow Designer.
 214 The Docker Compose files can be find in the workflow designer Git repository, under _docker-compose_ directory.
 215
 216 > In order to use this deployment method, you need to install Docker Compose as described on
 217 [Install Docker Compose](https://docs.docker.com/compose/install/) official page.
 218
 219 ## 1. Cassandra Database
 220
 221 Instantiation of a Cassandra database is not part of the the Docker Compose service. You may already have a running
 222 instance of Cassandra you want to use. It can be in a Docker container, on a VM, or a physical machine.
 223
 224 If you want to spin up a Cassandra database alongside the Workflow Designer service for development purposes,
 225 use the following command:
 226
 227 `docker-compose -p workflow -f cassandra.yml up -d`
 228
 229 > Note, that since the database was created under the same project (`-p workflow`), but as a separate service, it will
 230 keep running when you shut down the workflow designer service. This will cause an error message
 231 _ERROR: network workflow_default id <......> has active endpoints_.
 232
 233 ## 2. Environment Variables
 234
 235 Edit _.env_ file located in _docker-compose_ directory. Here is a brief overview of some variables.
 236
 237 - IMAGE_TAG &mdash; enables to try other versions of the Docker images
 238
 239 - REGISTRY &mdash; allows to use any Docker registry; leave it blank for locally built images
 240
 241 - CS_HOST &mdash; Cassandra host name or IP address. Keep in mind that the host must be accessible from the
 242 [Docker Compose network](https://docs.docker.com/compose/networking/) created for the workflow service.
 243 Use `CS_HOST=cassandra` if you created the database as described in the previous section.
 244
 245 - SDC_HOST &mdash; usually, IP address of the Docker host (if you are using the SDC deploy script).
 246
 247 - CASSANDRA_INIT_PORT &mdash; Cassandra Thrift port, usually 9160.
 248
 249 - CASSANDRA_PORT &mdash; Cassandra CQL native client port, usually 9042.
 250
 251 - BACKEND_DEBUG_PORT &mdash; *host* port used to debug the backend server (see below).
 252
 253 - FRONTEND_DEBUG_PORT &mdash; *host* port used to debug the frontend server (see below).
 254
 255 - FRONTEND_PORT &mdash; *host* port Workflow Designer UI will be accessible at.
 256
 257 > Other variables are described in _Deployment on Docker_ section.
 258
 259 ## 3. Starting Workflow Designer Service
 260
 261 Assuming the database is up and running, execute the following in the command line:
 262
 263 `docker-compose -p workflow up -d`.
 264
 265 It is easy to restart or recreate the entire service or a selected component using Docker Compose commands, for example
 266 to pick up new versions of the Docker images. Keep in mind that the database may remain unchanged, so that the new
 267 service will continue to work with old data.
 268
 269 For example, you can restart just the frontend by issuing the command:
 270
 271 `docker-compose -p workflow restart workflow-frontend`
 272
 273 Keep in mind that changes to the _docker-compose.yml_ configuration or environment variables
 274 [will not be reflected](https://docs.docker.com/compose/reference/restart/) when using `restart`. For that, you will
 275 need to recreate the container (e.g. to change the image version):
 276
 277 `docker-compose -p workflow up -d --no-deps workflow-frontend`
 278
 279 For more advanced features and commands, please refer to
 280 [Docker Compose documentation](https://docs.docker.com/compose/).
 281
 282 ## 4. Stopping Workflow Designer Service
 283
 284 You can shut down the entire stack of Workflow Designer components using
 285 `docker-compose -p workflow down`.
 286
 287 ## 5. Starting Workflow Designer in Debug Mode
 288
 289 It is possible to start the service in debug mode, when both the front-end and the back-end are accessible from a
 290 remote debugger at mapped host ports. Run:
 291
 292 `docker-compose -p workflow -f docker-compose.yml -f debug.yml up -d`.
 293
 294 SDC Plugin Configuration
 295 ========================
 296
 297 In order to run as an SDC pluggable designer, Workflow Designer must be added to SDC configuration as described in
 298 [Generic plugin support](https://wiki.onap.org/display/DW/Generic+Designer+Support).
 299
 300 If you are deploying SDC using a standard procedure (OOM or the
 301 [SDC shell script](https://wiki.onap.org/display/DW/Deploying+SDC+on+a+Linux+VM+for+Development)),
 302 the easiest way to configure the Workflow plugin is to edit the *plugins-configuration.yaml*.
 303
 304 ### Plugin Source
 305
 306 The main endpoint to load Workflow Designer Web application is defined by `"pluginSourceUrl": "http://<host>:<port>"`.
 307
 308 Keep in mind that the URL **must be accessible from a user's browser**. In most cases, `<host>` will be the hostname or
 309 IP address of the machine that runs Docker engine, and `<port>` will be a host port to which you have published port
 310 8080 of the Workflow frontend container.
 311
 312 ### Plugin Discovery
 313
 314 In order to check the availability of a plugin, SDC uses `"pluginDiscoveryUrl"`. For Workflow the value is
 315 `http://<host>:<port>/ping`.
 316
 317 ### Example
 318
 319 Let's assume that hostname of the machine that runs Docker containers with the Workflow application is
 320 *workflow.example.com*, and port 8080 of the Workflow frontend is mapped to 9088 on the host. In this case the
 321 corresponding section of *plugins-configuration.yaml* will look like below:
 322
 323 ```
 324
 325 - pluginId: WORKFLOW
 326      pluginDiscoveryUrl: "http://workflow.example.com:9088/ping"
 327      pluginSourceUrl: "http://workflow.example.com:9088"
 328      pluginStateUrl: "workflowDesigner"
 329      pluginDisplayOptions:
 330         tab:
 331             displayName: "WORKFLOW"
 332             displayRoles: ["DESIGNER", "TESTER"]
 333
 334 ```
 335
 336 In a development or demo environment, Workflow Designer will run on the same host as SDC, so that its IP address will
 337 be the one of the Docker host.