# Usage

## Overview

This page presents the common use cases of the WorkflowGen upgrade image. This image is available as Linux and Windows containers, and is meant to be a single use container that runs until completion. You should delete it once you're done with it.

## Upgrade steps

The first thing to know about the upgrade container is the steps it takes to upgrade your installation. Except for the acquisition of the update package, every step is done within a transaction, which means that any error will revert all changes previously made. In the case of files, they will be restored from a backup done prior to the operation.

### Step 1: Get the update package

Depending on if the upgrade container is online or offline, this step gets the update package of the `ToVersion` parameter. If the container is online, it will try to get the update package from the `updatepackages` volume first. If not found, the container will download it from the `workflowgen-releases` GitHub repository. If the container is offline, it will try to get the update package from the `updatepackages` volume. If it can't, it will write an error message and exit.

You have to provide your own WorkflowGen update packages when using the container offline. By default, when you mount the `updatepackages` volume, the container expects the following file structure:

```
updatepackages/
    7.14.0/
        update.zip
    7.15.0/
        update.zip
```

As you can see, the structure expected has only folders at the top level with the exact version of WorkflowGen. Inside them is an archive called `update.zip`, which is the WorkflowGen official update package. You need only to have the `ToVersion` update package when you run the container.

Optionally, if the update package is located elsewhere within the volume, you can specify the file name and path in the `WFGEN_UPGRADE_UPDATE_PACKAGE_FILE_NAME` environment variable. For example, you could specify the value `7.15.2.zip` if `ToVersion` is `7.15.2` and the directory structure is flat. You could also specify the value `workflowgen/updates/7.15.2/update.zip` if the update package is further down the directory tree.

For more information about environment variables, see the [Configuration](https://docs.workflowgen.com/docker/workflowgen-upgrade-image/upgrade-configuration) page of this section.

### Step 2: Merge new `App_Data` files into existing `App_Data` folder

Before this operation, a backup will be made of all the folders and files from within the bind mount and temporarily copied to a path inside the container. At all times, the `Files`, `LogFiles`, and `Ws` folders are ignored, including during the merge operation. The container will then merge the `App_Data` files from the update package into your `App_Data` folder that you have linked to the container through the data bind mount. The merge is additive only, which means that any file that don't exist in the update package will be kept as-is. 

### Step 3: Merge new `wfapps` files into existing `wfapps` folder

In the same manner as the `App_Data` merge operation, the `wfapps` folder will also be merged with your `wfapps` provided in the data bind mount. This operation is also additive only.

### Step 4: Migrate the database if needed

The upgrade container will then apply any SQL migration files found in the update package that satisfy the condition $$fv < x \le tv$$ where $$x$$ is the version of the SQL migration file, $$fv$$ is the `FromVersion` value and $$tv$$ is the `ToVersion` value.

## Online example

This is the simplest use of the upgrade container. For example, if you want to upgrade WorkflowGen from version 7.14.6 to 7.18.2 and the container has access to the Internet, you would call it like this:

{% tabs %}
{% tab title="PowerShell" %}

```powershell
# "wfgdata" groups appdata and wfapps folders
docker container run -i --name wfgen-upgrade `
    --env 'WFGEN_DATABASE_CONNECTION_STRING=Server=someserver,1433;...' `
    --mount "type=bind,src=C:\path\to\your\wfgdata,dst=/mnt/data" `
    advantys/workflowgen-upgrade:latest-ubuntu-18.04 `
    -FromVersion 7.14.6 -ToVersion 7.18.2

# When has terminated, you can analyse the container or review the logs.
# Then, remove the container.
docker container rm wfgen-upgrade
```

{% endtab %}

{% tab title="Bash" %}

```bash
# "wfgdata" groups appdata and wfapps folders
docker container run -i --name wfgen-upgrade \
    --env 'WFGEN_DATABASE_CONNECTION_STRING=Server=someserver,1433;...' \
    --mount type=bind,src=C:\path\to\your\wfgdata,dst=/mnt/data \
    advantys/workflowgen-upgrade:latest-ubuntu-18.04 \
    -FromVersion 7.14.6 -ToVersion 7.18.2

# When has terminated, you can analyse the container or review the logs.
# Then, remove the container.
docker container rm wfgen-upgrade
```

{% endtab %}
{% endtabs %}

In this example, the container will download the update package from the 7.18.2 version, merge the `App_Data` and `wfapps` files in `/mnt/data/appdata` and `/mnt/data/wfapps` respectively and apply any database migrations using the SQL scripts in the update package.

You can ignore files and folders with environment variables when the container merges files. For more information, see the [Configuration](https://docs.workflowgen.com/docker/workflowgen-upgrade-image/upgrade-configuration) page of this section.

## Offline example

If the container doesn't have access to the Internet, you can pass the WorkflowGen update package yourself. Make sure that it is the exact version of the `ToVersion` argument passed to the container. You would call the container like this:

{% tabs %}
{% tab title="PowerShell" %}

```powershell
# "wfgdata" groups appdata and wfapps folders
docker container run -i --name wfgen-upgrade `
    --env 'WFGEN_DATABASE_CONNECTION_STRING=Server=someserver,1433;...' `
    --mount "type=bind,src=C:\path\to\your\wfgdata,dst=/mnt/data" `
    --mount "type=bind,src=C:\path\to\packages,dst=/mnt/updatepackages" `
    advantys/workflowgen-upgrade:latest-ubuntu-18.04 `
    -FromVersion 7.14.6 -ToVersion 7.18.2 -Offline
```

{% endtab %}

{% tab title="Bash" %}

```bash
# "wfgdata" groups appdata and wfapps folders
docker container run -i --name wfgen-upgrade \
    --env 'WFGEN_DATABASE_CONNECTION_STRING=Server=someserver,1433;...' \
    --mount type=bind,src=C:\path\to\your\wfgdata,dst=/mnt/data \
    --mount type=bind,src=C:\path\to\packages,dst=/mnt/updatepackages \
    advantys/workflowgen-upgrade:latest-ubuntu-18.04 \
    -FromVersion 7.14.6 -ToVersion 7.18.2 -Offline
```

{% endtab %}
{% endtabs %}

In this example, there are two changes compared to the online example. First, a bind mount has been added for provisioning update packages. The container will first look in it to find an update package. Second, the `-Offline` flag has been passed to the container. This flag tells the container to not try to download the update package if it doesn't find the package in the bind mount. In other words, the container will not attempt any network-related access.

The path and name of the update package can be modified with environment variables. For more information, see the [Configuration](https://docs.workflowgen.com/docker/workflowgen-upgrade-image/upgrade-configuration) page of this section.