This section 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.
The first thing to know about the upgrade container is the steps it takes to upgrade your installation. Every step, except for the acquisition of the update package, 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.
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 section.
App_Data files into existing App_DataBefore 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.
wfapps files into existing wfappsIn 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.
The upgrade container will then apply any SQL migration files found in the update package that satisfy the condition fv < x <= tv where x is the version of the SQL migration file, fv is the FromVersion value and tv is the ToVersion value.
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:
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
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
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 page of this section.
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:
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
# "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
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 page of this section.
This section explains how to completely configure a WorkflowGen upgrade container. Some options are configured as environment variables and others are passed directly to the entry point script. It is available as Linux and Windows images.
Note: This image is not designed to be taken as a base image.
In the case of the upgrade image, the environment variables are arguments that you should not have to change often when upgrading WorkflowGen. That way, you can easily pass a file that defines those variables and reuse it between runs. Here's the list of available environment variables with their descriptions:
| Variables | Description & values |
|---|---|
WFGEN_UPGRADE_UPDATE_PACKAGES_PATH | A path local to the container where the update packages are located. See the Offline mode section of this page for more information. Default value:
|
WFGEN_UPGRADE_UPDATE_PACKAGE_FILE_NAME | The name of the update package archive to pick in the update packages
path for this upgrade. If no value is provided, <ToVersion>.zip will
be picked where <ToVersion> is passed as an argument to
the container. |
WFGEN_DATABASE_CONNECTION_STRING | Required variable
|
WFGEN_UPGRADE_EXCLUDE_FILES | Globally excluded files when copying Notes:
|
WFGEN_UPGRADE_EXCLUDE_FOLDERS | Globally excluded folders when copying Notes:
|
WFGEN_UPGRADE_APPDATA_EXCLUDE_FILES | Globally excluded files when copying Notes:
|
WFGEN_UPGRADE_WFAPPS_EXCLUDE_FILES | Globally excluded files when copying Notes:
|
WFGEN_UPGRADE_APPDATA_EXCLUDE_FOLDERS | Globally excluded folders when copying Notes:
|
WFGEN_UPGRADE_WFAPPS_EXCLUDE_FOLDERS | Globally excluded folders when copying Notes:
|
Script parameters define options to pass as arguments directly to the upgrade container. These arguments are more likely to be defined each time you run the container, which is why they are not in environment variables. Here's the help file of the entrypoint script. It describes every parameters, their grouping and a few examples:
NAME
/usr/local/bin/docker-entrypoint.ps1
SYNOPSIS
Entrypoint script for the upgrade container.
SYNTAX
/usr/local/bin/docker-entrypoint.ps1 -FromVersion <String> -ToVersion <String> [-RemainingArgs <Object>] [-Offline] [<CommonParameters>]
/usr/local/bin/docker-entrypoint.ps1 -Command -RemainingArgs <Object> [<CommonParameters>]
/usr/local/bin/docker-entrypoint.ps1 -Help [<CommonParameters>]
DESCRIPTION
This script will merge files for the App_Data and wfapps directory between
the upgrade package of the destination version and the current installation
ones (passed as volumes).
It will also launch the required SQL migration scripts in order from lowest
to highest version. Make sure to use a SQL account that has the proper
rights to modify the database tables.
The "Files", "LogFiles" and "Ws" subfolders in App_Data are always ignored.
You don't have to specify them in the exclusion environment variables.
PARAMETERS
-FromVersion <String>
The current version of WorkflowGen. The starting version of the
migration.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-ToVersion <String>
The version to which you want to migrate the current one.
Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Command [<SwitchParameter>]
Indicates to execute a command inside the container. This is used in
conjunction with RemainingArgs
Required? true
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-RemainingArgs <Object>
Commands to execute inside the container. If versions are not passed, it is
executed at the beginning and then it exits after the execution. If
versions are passed, it is executed at the end of the script.
Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Help [<SwitchParameter>]
Get full help for this script.
Required? true
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
-Offline [<SwitchParameter>]
If provided, the script will not try to download the update package.
This means that you have to provide the update package from a volume.
Required? false
Position? named
Default value False
Accept pipeline input? false
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable.
For more information, see about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).
NOTES
File name: docker-entrypoint.ps1
requires -Version 7.0
-------------------------- EXAMPLE 1 --------------------------
PS > docker container run -i "..." advantys/workflowgen-upgrade:latest-ubuntu-18.04 -Help
Displays the full help for the container.
-------------------------- EXAMPLE 2 --------------------------
PS > docker container run -i "..." advantys/workflowgen-upgrade:latest-ubuntu-18.04 -Command dir /mnt/appdata
This executes an arbitrary command inside the container. It can be useful
for debugging network issues or other problems prior to the migration.
-------------------------- EXAMPLE 3 --------------------------
PS > docker container run -i "..." advantys/workflowgen-upgrade:latest-ubuntu-18.04 -FromVersion 7.14.10 -ToVersion 7.18.2
This will launch the migration process to upgrade WorkflowGen from version
7.14.10 to the 7.18.2 version.
-------------------------- EXAMPLE 4 --------------------------
PS > docker container run -i "..." advantys/workflowgen-upgrade:latest-ubuntu-18.04 -FromVersion 7.14.10 -ToVersion 7.18.2 dir /mnt/appdata
This will launch the migration process to upgrade WorkflowGen from version
7.14.10 to the 7.18.2 version. In addition, it will execute an arbitrary command
at the end of the migration process.
docker pull advantys/workflowgen-upgrade