# Getting Started

## Overview

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

## 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:

![](https://3571244637-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LnOnQxQ9iO8Mo5-FRAX%2F-M8WAPCvhieBzR_gOHlp%2F-M8WAoXuM1qgtsa0DRow%2Fadvantys_wfg_for_docker%20-%20getting_started_docker.svg?alt=media\&token=e9823192-1c50-44eb-8683-27d57b4cc6a7)

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](https://docs.docker.com/desktop/) guide to install Docker for Windows. You must be using Windows containers, so you need at least Windows 10 Pro.

**For Windows Server**

{% hint style="warning" %}
Do not install Docker for Windows on Windows Server. It is designed for development only.
{% endhint %}

{% hint style="info" %}
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.
{% endhint %}

Follow the instructions in the [Docker Desktop](https://docs.docker.com/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:9.3.1-express-win-ltsc2019
```

{% hint style="info" %}

* If you're using a different version of WorkflowGen, replace `9.3.1` in the command above with your version number.
* 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`).
  {% endhint %}

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](https://docs.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/persistent-storage) 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:9.3.1-express-win-ltsc2019
```

{% hint style="info" %}
If you're using a different version of WorkflowGen, replace `9.3.1` in the command above with your version number.
{% endhint %}

This last command will set the passwords of the SA database user, the `WFGEN_USER` database user, and the `wfgen_admin` WorkflowGen account as`strong(!)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:9.3.1-win-ltsc2019
```

{% hint style="info" %}

* If you're using a different version of WorkflowGen, replace `9.3.1` in the command above with your version number.
* Don't forget to use the correct tag for your version of Windows (see [Global prerequisites](#global-prerequisites) above).
  {% endhint %}

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:9.3.1-win-ltsc2019
```

{% hint style="info" %}
If you're using a different version of WorkflowGen, replace `9.3.1` in the command above with your version number.
{% endhint %}

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 $_ }
```

{% hint style="warning" %}

* 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.
  {% endhint %}

### 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](https://docs.docker.com/compose/).

### Architecture overview

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

![](https://3571244637-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LnOnQxQ9iO8Mo5-FRAX%2F-M8WAPCvhieBzR_gOHlp%2F-M8WAoXuM1qgtsa0DRow%2Fadvantys_wfg_for_docker%20-%20getting_started_docker.svg?alt=media\&token=e9823192-1c50-44eb-8683-27d57b4cc6a7)

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](https://docs.docker.com/desktop/) guide to install Docker for Windows. You must be using Windows containers, so you need at least Windows 10 Pro.

**For Windows Server**

{% hint style="warning" %}
Do not install Docker for Windows on Windows Server. It is designed for development only.
{% endhint %}

{% hint style="info" %}
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.&#x20;
{% endhint %}

Follow the instructions for Windows Server in the [Docker Desktop](https://docs.docker.com/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](https://docs.docker.com/compose/install/) 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;
```

{% hint style="info" %}
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.
{% endhint %}

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:

```yaml
version: '3.8'
services:
  workflowgen:
    image: advantys/workflowgen:9.3.1-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:9.3.1-express-win-ltsc2019
    env_file:
      - '.\database.env'
    volumes:
      - 'sqldata:C:\wfgen\sql'

volumes:
  wfgdata:
  licenses:
    external: true
  sqldata:

```

{% hint style="info" %}
If you're using a different version of WorkflowGen, replace `9.3.1` in the command above with your version number.
{% endhint %}

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.