Links

Release Bundle

Release Bundle block utilizes the atomic release cycle from JFrog to deploy your entire application to your edge devices.
Release Bundle is only available with a JFrog Enterprise+ subscription.

What is Release Bundle?

Release Bundles group together the contents that are part of your release, providing the bill of materials for your software releases. For example, you can group together the different build artifacts, such as Docker images, that make up your software release that can then be pushed to your point of sale devices.
A Release Bundle plays a central role in the distribution flow. It specifies the different files and packages that comprise a release, along with their metadata, and is created and managed in JFrog Distribution. Release Bundles are generally distributed from a source Artifactory instance to an Artifactory Edge node. Since all the files specified in a release bundle are required to keep the release coherent, a release bundle is immutable. Effectively, this means that once a file has been included in a release bundle, it cannot be deleted from the Edge node where it is hosted.
To read more on Release Bundle, Check the docs.

Overview

Release Bundle block allows you to select a Release Bundle version so its content (artifacts) will be downloaded to your edge devices during the update deployment. Optionally, if the Release Bundle contains Docker images, containers can be executed using docker-compose.
Requires incorporation of Artifactory, see JFrog Account Integration.
Requires Agent Version 6.0 and above.
Deployments using the Release Bundle overwrite the entirety of the files in the directory, therefore, a Release Bundle must be a complete bundle of your software, including all dependencies.

Release Bundle Versioning

As Release Bundles are immutable, an atomic version of your software release, it is important to follow the best practice in order to properly version your releases and keep control over your artifacts.

Versioned Directories

Upon bundling, your files get signed and become immutable, therefore, it's important to divide your software into versioned directories as you update your artifacts.
The versioned structure is a user-created hierarchy of directories that is divided into different folders.
The user-created hierarchy of directories should not affect your application dependencies, it is an Artifactory-only configuration, read more.
For example, an application that is stored inside the app-files repository will be divided into version directories as follows:
  1. 1.
    Before creating the Release Bundle, create a directory under app-files that contains all of your applications, and name it with a version that represents the entire application as a whole.
2. By using this structure, you may create a Release Bundle over your V1 application, which will make them immutable.
3. When a binary needs to be updated, a new versioned directory will be used to store the new files that will eventually be bound together with another Release Bundle.

On-Device Hierarchy Dependency

The device will only contain the latest deployed version of the Release Bundle, any previous versions will be deleted upon deployment.
In order to ensure your application reliability on your edge devices, upon the deployment of the Release Bundle, keep in mind the following:
These items allow the device to be oblivious of your software in terms of Repository, Version and Dependency.
For example, When deploying V1 of app-files to /home/user/ the app-files/V1 hierarchy will be removed and the application will be stored as follows:
/home/user/<application binaries>
By removing the previous versions together with the Repository & V1 directories, the device will always run the latest release bundle version without relying on a dependency such as the version directory name.

Configuration

JFrog Account

Select your JFrog Account, if it does not exist, please follow our JFrog Account integration guidelines.

Release Bundle Name

Select the name of your Release Bundle.

Release Bundle Version

Select the version of the Release Bundle you want to deploy.

Destination Path on Device

The device path is the directory on the device that the Release Bundle will be pulled into.
  1. 1.
    The directory on the device must exist beforehand, otherwise, the update will fail.
  2. 2.
    A directory will be created with the name of the Release Bundle inside the chosen directory. All artifacts of the Release Bundle will be pulled into that directory.
For example:
If you choose a Release Bundle with the name: "my-release-bundle", and the destination path is: "/home/user/my-app", the final destination of all artifacts from the Release Bundle will be: "/home/user/my-app/my-release-bundle/"

Custom Paths

Custom paths let you choose specific artifacts from the Release Bundle that will be pulled into a different location than the chosen "Destination path". This might be useful when you have certain artifacts from the Release Bundle that must be placed in a specific location on the device.

Artifactory Path

Select the path in Artifactory where the file or directory is located.
The path can be either a directory or a specific file.
You may select multiple directories or files by pressing the Add Custom Path button.
The selected artifact must be part of the Release Bundle.

Destination Path on Device

The device path is the directory on the device that the selected custom artifact will be pulled into.
The directory on the device must exist beforehand, otherwise, the update will fail.
JFrog Connect does not automatically create directories when deploying updates, you may create a folder using the "Run Command" block in the General Section.
A good example for using the Custom Paths option is a systemd service file, which must be placed in "/etc/systemd/system/".
If you choose a Release Bundle with the name: "my-release-bundle", and the destination path is: "/home/user/my-app"
then you choose a Custom Path as follows: the Artficatory path is: "generic-repo/v1/my_app.service", the destination path is: "/etc/systemd/system/"
then the final destination of all artifacts from the Release Bundle will be: "/home/user/my-app/my-release-bundle/" and only the "my_app.service" file will be placed in "/etc/systemd/system/".

Docker Compose

If the Release Bundle contains Docker Images, JFrog Connect provides an option to deploy containers from them using docker-compose.

Prerequisites

  • Docker images are stored in JFrog Container Registry which is part of the Release Bundle.
  • docker installed on your devices.
  • docker compose or docker-compose installed on your devices.
  • A docker-compose configuration file located inside the Release Bundle.

Artifactory Path

Select the path in JFrog Artifactory where the docker-compose file is located.
The selected artifact must be part of the Release Bundle.

Destination Path on Device

The directory on the device that the docker-compose file will be pulled into.
This is also the project-directory for the docker-compose binary (read more).
The directory on the device must exist beforehand, otherwise, the update will fail.
JFrog Connect does not automatically create directories when deploying updates, you may create a folder using the "Run Command" block in the General Section.

On Fail

Allows you to define the occurrences upon failure of the JFrog Release Bundle block.
By default, when the block fails, all downloaded artifacts from the Release Bundle will be automatically reverted. You can disable this option in the On Fail tab.

Docker Compose

By default, when the block fails, the docker-compose file automatically reverted to the previous state.
Failures that are caused from container logic (e.g., Command fails, Invalid image architecture) are handled by the docker-compose binary and are not regarded as a block failure.
It is recommended to add restart: always to your service configurations in order to make sure docker-compose automatically restarts the service.
In order to allow a Rollback functionality, deployments require your device's free memory to be higher than the update size.
To calculate how much free memory is required, follow the equation below
Free Memory Required > Current directory size + Update size + 10MB
To read more about On Fail configuration, refer to the Rollback section.