General updating concepts

The updating process will involve some or all of the steps below and will at least involve the portal’s technical administrator and potentially a scientist responsible for the portal’s scientific settings (e.g. someone who would know information such as the assays and ion channels being processed) :

The steps are :

  1. Reflect any new files in the portal repository source code onto the local system, i.e., create files according to any modified installation instruction documentation file(s).

  2. Reflect any modifications to the portal repository sample.<file_name> files onto the local configuration files (which were originally created during installation).
    Details of files which may have been modified may be found in the ChangeLog.

  3. Reflect any modifications to the portal repository files onto site-specific (including bespoke) code and configurations.

    This may be necessary if, for example, the business-manager-api or business-manager code changes, and there is bespoke, site-specific code which references any of the changed objects or settings.

  4. If you have more than one installation environment to maintain, e.g. development, test and production, then for each update in the feeder environment please record the modifications made so that accumulated changes can be applied to the consumer environment.

    In theory, a scientist would only need to present for the update of a development environment as changes to the test and/or production environment could be derived from recorded decisions made during the update of the development environment.

    See here as an example.

Retrieving and analysing changes in portal source code

In order to update the generic portal components the standard procedure is to execute the following git commands in sequence at the base of the cloned AP-Portal directory. A collection of the latest command examples is stored in the tools section :

  1. git fetch

    (Outcome: Does not update the local source code files or directories , only updates git’s internal version control system, but allows us to anticipate what changes will be required locally.)

  2. git diff --name-status HEAD...<git hash>, or
    git diff --name-status HEAD...origin

    (Outcome: Lists the source code file changes and the nature of change)

    Generally we focus on the (M)odified, (D)eleted or (A)dded of the following file types, but also check the ChangeLog:

    1. sample.<file_name>
    2. .gitignore
    3. <file_name>.xsd
    4. installation/components/<component>/index.rst

    A sample command would be git diff --name-status HEAD...origin | grep -P '(/sample\.|\.gitignore|\.xsd|installation/components/.*?/index\.rst$|/appCtx\.config\.|/pom\.xml|\.sql)'

    If any changes have been made to the source code of such files please record their names for closer examination in the next step.

  3. git diff HEAD...<git hash> <file_name>, or
    git diff HEAD...origin <file_name>

    (Outcome: Prints a diff output of the changes of a specified file if it has been (M)odified since the last git merge origin.)

    Determine what, if any, local changes will be required after an instruction to “merge” the update (see next step) is executed. See Updating configuration and settings files and Updating web services.

  4. git merge <git hash>, or
    git merge origin

    (Outcome: Updates the source code files and directories.)

Updating configuration and settings files

During the original installation of each of the components it is very likely that site-specific configurations were derived from generic configuration or settings files, e.g. files such as src/properties/filter.properties derived from their corresponding “sample” file src/properties/sample.filter.properties, or in the case of the client portal, Bespoke site-business functionality. Invariably these instructions were defined in the component’s installation instruction file.

If the content of the “sample” files has been changed by the update request (e.g. perhaps a new configuration option has been added to a component) then any such changes will need to be implemented in the derived site-specific implementations of those files.

At this stage the best option is to view the output of the git diff --name-status HEAD...origin command to check which of the files listed in a component’s installation instructions documentation file have been modified and manually apply changes to the local version.

Updating web services

If any of the components’ WS XSD files have been modified (usually located in the component’s src/main/resources/META-INF/schema/ directory) then, if the change results in a change of contract (as opposed to a change of documentation) of the component’s WS API, any components with which it communicates may also need to be updated.

Restarting components

Once any changes have been made to configuration and settings files the components need to be rebuilt (see Build instructions in Installation), redeployed and restarted.