Getting Started

Overview

This section presents how to quickly run the WorkflowGen container with a minimal architecture on your local machine.

There are known limitations when using Hyper-V isolation with the WorkflowGen container in WorkflowGen versions 7.19.2 and earlier. It's recommended to use process isolation exclusively. This limitation no longer applies as of WorkflowGen version 7.20.0.

Global prerequisites

• Make sure to have a valid WorkflowGen license.

• If you're using Windows Server, make sure that it's Windows Server 2019, and use the tag that corresponds to that version. For example, for Windows Server 2019, use the tag that ends with ltsc2019.

Docker manual local machine deployment

Architecture overview

At the end of this section, the following architecture will be deployed on your local machine:

Inside the Docker engine on your machine, you'll have a running WorkflowGen server and a WorkflowGen database. Both of these will use volumes mapped to your local machine to persist data files.

Prerequisites

Make sure to have installed Docker on your machine.

For Windows 10 Pro

Follow the instructions in the Docker Desktop guide to install Docker for Windows. You must be using Windows containers, so you need at least Windows 10 Pro.

For Windows Server

Do not install Docker for Windows on Windows Server. It is designed for development only.

If you've provisioned a virtual machine on your cloud provider where the template indicates something like Windows Server with Containers, it's probably safe to assume that Docker is already installed. Execute docker version on the machine to verify that it is. If so, you can skip the installation process.

Follow the instructions in the Docker Desktop guide to install Docker on Windows Server.

For this setup, it's recommended to use WorkflowGen's database Docker image. You can also use a SQL database installed on your local machine.

Run the database container

To download the database image into your local machine, open PowerShell and enter the following:

docker image pull advantys/workflowgen-sql:7.18.2-express-win-ltsc2019

• Don't forget to use the correct tag for your version of Windows.

• The Windows version of the advantys/workflowgen-sql image is designed for development or testing only. It is not suited for production workloads. Instead, consider using the Linux version of the image (e.g. advantys/workflowgen-sql:7.18.2-ubuntu-18.04).

For WorkflowGen to work, you need to run the database before running WorkflowGen. Before creating the container, create a Docker volume in order to externalize the database files (.mdf and .ldf). This will ensure that the data are still there after the deletion of the container.

docker volume create sqldata

The physical location of the volume can be obtained using the following command:

docker volume inspect -f "{{.Mountpoint}}" sqldata

Typically, it will be stored in C:\ProgramData\Docker\volumes\sqldata\_data. Make sure that the container has write access to this directory (see the Persistent Storage in Containers Microsoft article for information).

You're now ready to run the database container. To do this, execute the following command:

docker container run -it `
  --env ACCEPT_EULA=Y `
  --env 'SA_PASSWORD=strong(!)Pass' `
  --env WFGEN_DATABASE_USER_USERNAME=WFGEN_USER `
  --env 'WFGEN_DATABASE_USER_PASSWORD=strong(!)Pass' `
  --env 'WFGEN_ADMIN_PASSWORD=strong(!)Pass' `
  -v sqldata:C:\wfgen\sql `
  --name wfgen_sql `
  --hostname database `
  advantys/workflowgen-sql:7.18.2-express-win-ltsc2019

This last command will set the passwords of the SA database user, the WFGEN_USER database user, and the wfgen_admin WorkflowGen account asstrong(!)Pass. Per the nature of Docker, the SA_PASSWORD and ACCEPT_EULA environment variables come from the microsoft/mssql-server-windows-express base container and are not directly handled by the WorkflowGen container.

Run the WorkflowGen container

Enter the following to download the WorkflowGen image:

docker image pull advantys/workflowgen:7.18.2-win-ltsc2019

Don't forget to use the correct tag for your version of Windows (see Global prerequisites above).

For this container, you need two volumes in order to correctly persist the WorkflowGen data:

• WorkflowGen licenses (licenses)

• WorkflowGen's data (data), which contains the following:

  • The App_data folder (appdata )

  • Workflow applications (wfapps)

"licenses", "wfgdata" | ForEach-Object { docker volume create $_ }

You now need to copy your WorkflowGen license into the licenses volume. To do this, execute the following command:

Copy-Item C:\Path\To\WorkflowGen.lic $(docker volume inspect -f "{{.Mountpoint}}" licenses)

This way, the WorkflowGen container will be able to pick it up via the volume. You also need an encryption key for the container; use the following command to generate one:

[guid]::NewGuid().ToString('N')
# fda7a6a81db2428b8885bd1210522755

To run the actual container, replace <YOUR_WFG_LIC_KEY> with your WorkflowGen license key and <YOUR_NEW_GUID> with the GUID that you generated in the last step, then execute the following command:

docker container run -it `
  --env 'WFGEN_APP_SETTING_ApplicationUrl=http://localhost:8080/wfgen' `
  --env 'WFGEN_APP_SETTING_ApplicationSerialNumber=<YOUR_WFG_LIC_KEY>' `
  --env 'WFGEN_APP_SETTING_ApplicationSecurityPasswordSymmetricEncryptionKey=<YOUR_NEW_GUID>' `
  --env 'WFGEN_DATABASE_CONNECTION_STRING=Data Source=database,1433;Network Library=DBMSSOCN;Initial Catalog=WFGEN;User ID=WFGEN_USER;Password=strong(!)Pass;' `
  -p 8080:80 `
  -v wfgdata:C:\wfgen\data `
  -v licenses:C:\wfgen\licenses:RO `
  --name wfgen `
  advantys/workflowgen:7.18.2-win-ltsc2019

When the container is ready, open a browser and go to http://localhost:8080/wfgen, where you'll be prompted for WorkflowGen authentication. By default, the container is configured with the application authentication method.

Shut down the containers

Once you're done with this environment, you can shut down containers by stopping them. They can be restarted later.

# Stopping the containers
"wfgen", "wfgen_sql" | ForEach-Object { docker container stop $_ }

# Starting the containers
docker container start wfgen_sql
# Wait for the database to be ready and then start the WorkflowGen container
docker container start wfgen

# Restarting the containers
"wfgen_sql", "wfgen" | ForEach-Object { docker container restart $_ }

• Any environment variable defined will be reapplied after restarting a container. Therefore, any changes made to a web.config file without environment variables will not be carried between restarts or re-runs.

• This action keeps data in the container's file system between restarts. If you add a file that isn't in a volume, it will be kept after restarting.

Remove the containers

To completely remove containers, there's only one command to execute:

"wfgen", "wfgen_sql" | ForEach-Object { docker container rm -f $_ }

This will remove the database and WorkflowGen containers including, any manual change in the container's file system that is not part of a volume. Even if the containers are gone, the data in the volumes are retained and can be used by other containers. For example, you could launch three other WorkflowGen containers that use the same volumes and they will all get the exact same files at the mount point of the volume.

Docker Compose local machine deployment

This section describes the recommended way to easily deploy a local development environment without having to enter a lot of commands. You can find out more about Docker Compose in the Docker documentation at Overview of Docker Compose.

Architecture overview

At the end of this section, the following architecture will be deployed on your local machine:

Inside the Docker engine on your machine, you'll have a running WorkflowGen server and a WorkflowGen database. Both of these will use volumes mapped to your local machine to persist data files.

Prerequisites

For Windows 10 Pro

Follow the instructions in the Docker Desktop guide to install Docker for Windows. You must be using Windows containers, so you need at least Windows 10 Pro.

For Windows Server

Do not install Docker for Windows on Windows Server. It is designed for development only.

If you've provisioned a virtual machine on your cloud provider where the template indicates something like Windows Server with Containers, it's probably safe to assume that Docker is already installed; execute docker version on the machine to verify that it is. If so, you can skip the installation process.

Follow the instructions for Windows Server in the Docker Desktop guide to install Docker on Windows Server.

On Windows Server only, you also need to install the Docker Compose tool, since it's not installed by default. Follow the instructions for Windows Server in the Install Docker Compose guide. To verify that Docker Compose is properly installed, run the following command:

docker-compose version

For this setup, it's recommended to use WorkflowGen's database Docker image. You can also use a SQL database installed on your local machine.

Create the license volume

Before creating the services, you need to create the license volume externally from the composition in order to have the licenses present at the time of container creation. To do this, execute the following command:

docker volume create licenses

Then, you need to copy your license file to the licenses directory. The following command will show you where the license will be stored:

docker volume inspect -f "{{.Mountpoint}}" licenses

To copy your license, execute the following command:

Copy-Item C:\Path\To\WorkflowGen.lic $(docker volume inspect -f "{{.Mountpoint}}" licenses)

Create the symmetric encryption key

This value should be generated by you. A simple GUID will suffice since it has sufficient entropy not to be guessed:

[guid]::NewGuid().ToString('N')
# fda7a6a81db2428b8885bd1210522755

Create the environment files

For each service that you'll create (one for WorkflowGen and one for the database), you'll need a file that contains all of the environment variables for that service.

Database

Use the following file as a template:

SA_PASSWORD=strong(!)Pass
WFGEN_DATABASE_USER_USERNAME=WFGEN_USER
WFGEN_DATABASE_USER_PASSWORD=strong(!)Pass
WFGEN_ADMIN_PASSWORD=strong(!)Pass

Save it as database.env using the path where you'll put the Compose file.

WorkflowGen

Use the following file as a template:

WFGEN_APP_SETTING_ApplicationUrl=http://localhost:8080/wfgen
WFGEN_APP_SETTING_ApplicationSerialNumber=<YOUR_WFG_LIC_KEY>
WFGEN_APP_SETTING_ApplicationSecurityPasswordSymmetricEncryptionKey=<YOUR_NEW_GUID>
WFGEN_DATABASE_CONNECTION_STRING=Data Source=database,1433;Network Library=DBMSSOCN;Initial Catalog=WFGEN;User ID=WFGEN_USER;Password=strong(!)Pass;

Replace <YOUR_WFG_LIC_KEY> with the value of your WorkflowGen license key. Replace <YOUR_NEW_GUID> with the symmetric encryption key that you have generated earlier.

Save this file as workflowgen.env using the path where you'll put the Compose file.

Deploy the services

To deploy services with Docker Compose, you need a Compose file that describes them. Use the following Compose file for this example:

version: '3.8'
services:
  workflowgen:
    image: advantys/workflowgen:7.18.2-win-ltsc2019
    restart: always
    env_file:
      - '.\workflowgen.env'
    ports:
      - '8080:80'
    volumes:
      - 'wfgdata:C:\wfgen\data'
      - 'licenses:C:\wfgen\licenses:RO'
    depends_on:
      - database
  database:
    image: advantys/workflowgen-sql:7.18.2-express-win-ltsc2019
    env_file:
      - '.\database.env'
    volumes:
      - 'sqldata:C:\wfgen\sql'

volumes:
  wfgdata:
  licenses:
    external: true
  sqldata:

Save this file as docker-compose.yml using the path where you put your environment variable files, then execute the following command:

Set-Location C:\Path\To\ComposeFile
docker-compose up

Wait a few minutes for the containers to get started, then open a browser and navigate to http://localhost:8080/wfgen, where you will be prompted for authentication. Enter the credentials (username wfgen_admin and password strong(!)Pass) and it should display the WorkflowGen home page.