Documentation survey

Best practices

1. Deploying new images

This file describes how to deploy a new image on selected terminals first, test it, and then deploy it to all terminals.

The hardware type group (i.e. HWTYPE group) is used for booting new terminals, while already deployed terminals can be moved to any group that provides the Saltboot formula. This flexibility allows for testing of new images or configurations.

Procedure: Dual group image deployment

  1. Build new image. Use image synchronization formula to synchronize the image to all Branch Servers.

  2. Create a test group.

    • Name the group, for example, TEST:POSVendor-Terminal. The name can be chosen freely.

    • Add the Saltboot formula to this group. Use the same configuration as in the original hardware type group (HWTYPE), except for the image version. Use the name and version of the new image.

  3. Move selected terminals.

    • Identify the terminals you want to test the new image on.

    • Transfer these terminals from the group HWTYPE:POSVendor-Terminal group to the newly created group TEST:POSVendor-Terminal. It is recommended to use System Set Manager for this task.

  4. Reboot terminals.

    • Power on the selected POS terminals. They should boot the new image.

  5. Verify and evaluate.

    • Monitor the terminals in the TEST:POSVendor-Terminal group.

    • Check if the new image performs as expected and if there are any issues or errors encountered.

  6. Update HWTYPE group.

    • Once you have confirmed that the new image works correctly, the HWTYPE group can be updated.

    • Modify the image version in the HWTYPE:POSVendor-Terminal group to match the tested and approved version.

    • This ensures that all other terminals receive the new image.

1.1. Controlling image versions

By default, Saltboot formula selects the specified image name and version or selects the highest one if the version is not specified.

There are multiple methods to control the image version within the HWTYPE and TEST groups:

  • Specify exact version.

    • In both the HWTYPE and TEST groups, specify explicitly the exact version of the image to be deployed.

    • Make sure that the specified image version is already synchronized.

  • Mark new image as Inactive.

    • In the HWTYPE group, do not specify the image version.

    • Mark the new image as Inactive after building and before synchronizing it to Branch Server.

    • The Inactive flag ensures, that the image is not auto-selected when the image version is not specified.

    • After testing, remove the Inactive flag so the image can be auto-selected in the HWTYPE group.

    • The Inactive flag can be accessed through the API. For more information, see Image Pillars.

  • Utilize Freeze Image flag.

    • In the HWTYPE group, omit the image version.

    • Before synchronizing the new image, set the Freeze Image flag in Saltboot formula in HWTYPE group. This ensures that the already deployed terminals in this group will keep the old image.

    • Synchronize and test the new image in the TEST group.

    • Reset the Freeze Image flag in HWTYPE group, so the terminals in this group will be updated to the new image too.

Do not use the whitelist in Image Synchronization formula to control which terminal boots which image. It does not provide the required granularity and does not work with containerized Branch Server.