Partner Update v4

Overview

This section describes the Partner Platform v4 version of Update. As of this writing (Spring 2014), v4 is the standard shipping version of Update.

Partner Update is the application and subsystem responsible for maintaining the coherency of all Partner installations.

Update follows a hierarchical model, where installations of higher authority update those of lower authority, but those of lower authority can have increasingly specific configuration that they control.

Update is responsible both for initial installation and for upgrading existing installations.

Update directly modifies the following types of files in an installation:

  • config
  • modules
  • system
  • os

Update indirectly modifies data files through the Migration subsystem.

The Partner System has always been designed as a tool for organizations, rather than single users. As such, we have tried to simplify installation maintenance as much as possible by automating the installation and installation update process.

Update uses standard web server protocols to distribute file updates. Updates flow from “source” installations, which are generally some sort of master copy, to “destination” installs. Compression and incremental update techniques are used to minimize bandwidth usage. When started, the Map Viewer application checks with its last update source to see if updates are available, and if so asks the user if they want to update.

Java Web Start

Partner Update itself runs using the operating system’s copy of Java. See ../java/index for details.

The reason for this is that, under Microsoft Windows operating systems, Update is responsible for updating the embedded version of Java that Partner uses. Microsoft Windows is aggressive about file locking and it is impossible to remove files that are in use.

Update Hierarchy

Updates follow a hierarchical scheme, where every installation is updated from an install with the authority to overwrite some portion of the installation filesystem.

Installations “higher” in the hierarchy are more generic than those that are “lower”. Thus, each level of the hierarchy adds its own customizations, which it has sole responsibility for.

The filesystem has been specifically designed to simplify updates, and to make it clear which files are controlled by which installation. Since there is no overlap in responsibility, you can go to a any higher level install for an update. This is useful when, for example, you want to try a new version of the code without replacing your local configuration or installing the untested code on your Central Hub.

Here are the levels of the hierarchy, from most generic to most specific:

  • distribution
  • provider
  • customer
  • hub
  • site
  • seat

distribution

The software as distributed by Partner, with no user-specific configuration at all. Distribution files are located in the system/ and os/ directories.

provider

Software, configuration, and data provided by a third-party reseller. Provider files are located in config/provider and modules/provider.

customer

Software, configuration, and data provided by the customer organization. Customer files are located in config/customer/, modules/customer, and maps/.

hub

Hub is a bit of an anomaly; it’s managed at the same level as customer but is only propagated to hub-type installations. Typical configuration and modules in hub are database servers and web servers. Hub files are located in config/hub and modules/hub.

site

Software, configuration, and data provided by the district, workgroup, or other site. Site files are located in config/site and modules/site.

seat

Software, configuration, and data that is only available on a specific installation. Seat files are located in config/seat and modules/seat.

Install Types

Installation types are related to the hierarchy levels, but also reflect specific roles for an installation in the system.

  • Distribution
  • Provider
  • Master Install
  • Central Hub
  • Site Hub
  • User

More may be added in the future.

The type is defined in the file update/info/InstallType.txt.

Mechanics

This is how the installer works:

  1. user goes to source installation web page
  2. user chooses a standard or custom installation (configuring the custom with install type and path).
  3. user runs the updater from the web page
  4. the updater installs to the correct directory, doing an incremental update as described below

This is how the updater works:

  1. user starts the Map Viewer, which checks checksums and determines if an update is required,
  2. if the user says yes, update is run from the last website installed from
  3. update goes to the source web site to see what’s available
  4. update compares the install types of the source and destination (update/InstallType.txt)
  5. update determines which packages need to be propagated
  6. for each package:
  1. checksums are compared between source and destination
  2. if they differ the package (update/packages/*.boxcar.gz) file is downloaded
  3. existing directory trees in the package are deleted to ensure that cruft doesn’t accumulate
  4. the package file is unpacked
  1. final scripts (icon generation etc.) are run
  2. Map Viewer restarts

If anything goes wrong, an error message is shown to the user. Otherwise the program silently exits.

Often, running the program again will fix any problems.

You can manually run the Updater from e.g. os/windows/programs/Update.bat or from the shortcut in the Start Menu.

Using a shared hosting service

Partner uses Dreamhost, a Debian Linux-based shared web hosting provider, to host all software updates and demos. We have done our best to make scenarios such as this easy. In general, simply uploading the Partner4.4/update directory from the Map Publisher is sufficient.

For example, suppose you are a service provider that generates maps for several customers, and you want to provide them as Partner Map Viewer installs on a shared-hosting web server. Set up multiple translators, one per customer, and configure them to upload the Partner4.0 directory to different places in your shared hosting account. You could even secure it with the right configuration, so they need a password. Suppose Partner had such a service organization (we don’t, and won’t, but just suppose). The domain might be mapservice.partnersoft.com, and you might have the following installs available:

Relaunching after Update

By default, on User installations, the Map Viewer will be relaunched after the ModuleMigration step is complete. A preference setting controls whether the user is prompted for this or it does it automatically.

To relaunch other apps, you can write a file to data/update/RelaunchApp.txt. For example, the Workbench writes “Workbench” in this file when you run Update from the Workbench.

See the file reference for data/update/RelaunchApp.txt for more details.