advantys/workflowgen-upgrade

By advantys

Updated almost 4 years ago

Image

299

Usage

Overview

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.

Upgrade steps

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.

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 section.

Step 2: Merge new App_Data files into existing App_Data

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

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

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.

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:

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.

Configuration

Overview

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.

Environment variables

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:

VariablesDescription & 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:

  • Windows: C:\wfgen\updatepackages
  • Linux: /mnt/updatepackages
WFGEN_UPGRADE_UPDATE_PACKAGE_FILE_NAMEThe 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


The connection string to the WorkflowGen database. The user passed must have the rights to modify the schema of the database.

WFGEN_UPGRADE_EXCLUDE_FILES

Globally excluded files when copying App_Data files from the update package to your App_Data volume, and when copying wfapps files from the update package to your wfapps volume. The elements in this list must be comma-separated (e.g.myfile.txt,myfile2.txt).

Notes:

  • There is no distinction between files and folders in the Linux version.
  • Excluded files in Windows version are recursive.
  • You can't use sub-paths in Windows version.
WFGEN_UPGRADE_EXCLUDE_FOLDERS

Globally excluded folders when copying App_Data files from the update package to your App_Data volume, and when copying wfapps files from the update package to your wfapps volume. The elements in this list must be comma-separated (e.g.myfolder,myfolder).

Notes:

  • There is no distinction between files and folders in the Linux version.
  • Excluded folders in the Windows version are recursive.
  • You can't use sub-paths in the Windows version.
WFGEN_UPGRADE_APPDATA_EXCLUDE_FILES

Globally excluded files when copying App_Data files from the update package to your App_Data volume. The elements in this list must be comma-separated (e.g.myfile.txt,myfile2.txt).

Notes:

  • There is no distinction between files and folders in the Linux version.
  • Excluded files in the Windows version are recursive.
  • You can't use sub-paths in the Windows version.
WFGEN_UPGRADE_WFAPPS_EXCLUDE_FILES

Globally excluded files when copying wfapps files from the update package to your wfapps volume. The elements in this list must be comma-separated (e.g.myfile.txt,myfile2.txt).

Notes:

  • There is no distinction between files and folders in the Linux version.
  • Excluded files in the Windows version are recursive.
  • You can't use sub-paths in the Windows version.
WFGEN_UPGRADE_APPDATA_EXCLUDE_FOLDERS

Globally excluded folders when copying App_Data files from the update package to your App_Data volume. The elements in this list must be comma-separated (e.g. myfolder,myfolder).

Notes:

  • There is no distinction between files and folders in the Linux version.
  • Excluded folders in the Windows version are recursive.
  • You can't use sub-paths in the Windows version.
WFGEN_UPGRADE_WFAPPS_EXCLUDE_FOLDERS

Globally excluded folders when copying wfapps files from the update package to your wfapps volume. The elements in this list must be comma-separated (e.g. myfolder,myfolder).

Notes:

  • There is no distinction between files and folders in the Linux version.
  • Excluded folders in the Windows version are recursive.
  • You can't use sub-paths in the Windows version.

Script parameters

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 Command

docker pull advantys/workflowgen-upgrade