Ask Reuben

GBC Monthly Releases

How do you prepare your environment for monthly releases of GBC?

One of the things I repeated a couple of times during the recent WWDC was that in my opinion you should prepare your environments to receive monthly releases of the GBC and be in a position to switch quickly between GBC releases.  You want to be able to switch quickly so that you can

  • upgrade simply to the latest monthly GBC release every month
  • rollback equally simply to the previous release if there is an issue with the latest release
  • switch quickly between standard and your customisation to identify if an issue lies with your customisation or standard
  • switch quickly between current and previous versions to identify if an issue also occurred in previous versions

To quickly switch between environments it helps to be consistent on where you download and build your gbc packages.  I will use /opt/fourjs/gbc/{version}[_{customisation-name}].  So /opt/fourjs/gbc/5.00.08 /opt/fourjs/gbc/5.00.09 etc for the runtime packages and /opt/fourjs/gbc/5.00.08_sample, /opt/fourjs/gbc/5.00.09_sample etc. for some customization.  You are free to adopt your own convention.

The key to these steps is understanding how is the GBC package used at runtime is determined.  This varies by connection method.

You should note that in FGLDIR/web_utilities/gbc/gbc a version of the GBC is bundled inside the FGL package.  This is the package of last resort.  Unless otherwise specified, this is the version that will be used if none else can be found.


Direct Connection

If using Direct Connection, then the important environment variable is FGLGBCDIR.  As the documentation says ..

The GBC component will be searched in the following directories

  1. The appdir/gbc directory, where appdir is the directory where the program file is located,
  2. The directory defined in the FGLGBCDIR environment variable
  3. The $FGLDIR/web_utilities/gbc/gbc directory.

The use of appdir/gbc is intended for the case where you deploy your application with a specified GBC package.  In that instance you bundle a gbc in within your program files which is what occurs with a mobile app, and you may choose to do with your application.  With this approach if you want to change GBC package you are building and deploying another application.

If no gbc is bundled in with your program files then you can point at any GBC specified by the FGLGBCDIR environment variables.  In a development environment using Direct Connection then this is how you would rapidly switch between different GBC packages.  You might execute a series of steps like

export FGLGBCDIR=/opt/fourjs/gbc/5.00.08
fglrun demo &
export FGLGBCDIR=/opt/fourjs/gbc/5.00.09
fglrun demo &

to run two copies of demo using two different GBC versions and compare.


Genero Application Server

If running via Genero Application Server, the two important configuration elements inside your GAS configuration are GBC_LOOKUP_PATH and GBC.

The GAS looks in the directories specified by GBC_LOOKUP_PATH for an entry GBC.

If you look at FGLASDIR/etc/as.xcf you will see that GBC_LOOKUP_PATH has 3 values

  • $(res.path.gbc.user) – this is so that you can add your own directory or override it when the dispatcher is started using the -E dispatcher argument.
  • $(res.gbc.deployment) – this is a directory that the GAS deployment mechanism uses, I will explain that in the next section
  • $(res.fgldir)/web_utilities/gbc – the fallback to the GBC bundled with the FGL package

The neat thing about the use of GBC_LOOKUP_PATH is that you can use ?gbc= as part of the URL to quickly run different GBC.

So by using $(res.path.gbc.user) or adding your own entry within GBC_LOOKUP_PATH, placing all the standard and customised GBC in this directory, you can quickly switch between different GBC packages simply by using different ?gbc= arguments.  So I can use the following to quickly switch betweenthe standard 5.00.08, 5.00.09, and customisations 5.00.08_sample, 5.00.09_sample

  • http://localhost:6394/ua/r/gwc-demo?gbc=5.00.08,
  • http://localhost:6394/ua/r/gwc-demo?gbc=5.00.09
  • http://localhost:6394/ua/r/gwc-demo?gbc=5.00.08_sample
  • http://localhost:6394/ua/r/gwc-demo?gbc=5.00.09_sample

gasadmin gbc

The gasadmin tool has a verb gbc which can be used to manage GBC packages and switch between them.

  • The command gasadmin gbc --deploy copies GBC packages into the directory specified by$(res.gbc.deployment) I mentioned in the previous section
  • The command gasadmin gbc --list lists the packages that are in that directory
  • The command gasadmin gbc --default specified which of these packages to use as the default GBC.

So with a produciton site you might have executed to copy the GBC packages into your Application Server…

gasadmin gbc --deploy /opt/fourjs/gbc/5.00.08

gasadmin gbc --deploy /opt/fourjs/gbc/5.00.09

and then you can quickly switch between them using commands like …

gasadmin gbc --default 5.00.08

gasadmin gbc --default 5.00.09

How the default argument works is via the following…

You might have noticed in the GBC documentation the following …

  • If it is a directory, it is expected to have a compiled GBC customization or an unzipped GBC runtime package downloaded from the Four Js website.
  • If it is a file, then the file is expected to contain one line of text, giving the name of a directory located in the same directory as the file. This directory is expected to have a compiled GBC customization or an unzipped GBC runtime package downloaded from the Four Js website.

    If you look at default value of GBC in FGLASDIR/etc/as.xcf it is “_default”.  If you look inside $FGLDIR/web_utilities/gbc you will see a file _default and a directory gbc.  The file “_default” has one line text with the value “gbc” This _default file is read to give the gbc folder.  Same thing happens in the deployment folder.  Using –default changes the value inside the _default folder to point to a different folder in the deployment directory.

    So if a new package comes along, in production you might go

    • install the package using gasadmin gbc --deploy 5.00.10
    • test it using http://localhost:6394/ua/r/gwc-demo/?gbc=5.00.10
    • switch to it using gasadmin gbc --default 5.00.10
    • compare against previous using http://localhost:6394/ua/r/gwc-demo/?gbc=5.00.09
    • if there is a problem and you need to back out to the previous version, gasadmin gbc --default 5.00.09

    Final Points

    When deploying a new GBC you may choose to gradually roll it out to your user base.    For instance you may decide to make it available to head offices on day 1 and remote offices the following day.  That type of thing is possible.  It is similar to giving different users different customisations

    You aren’t expected to have many customisations.  Use concept of Themes within customisations if you want different appearances for different groups of users.

    There is no fixed date for GBC Monthly Releases.  An urgent bug fix may see a release close together.  If there is no urgent bug fixes there maybe a longer gap to allow more work to be carried out.

    The important thing is to be in a position where you can quickly switch between new standard GBC packages and different versions of your customised GBC packages.