App descriptor: Version 3

Introduction

An app descriptor declares that a version of the application is available at a given base URL, from which its packages (that is, one or more zip archives containing the application files) will be downloaded.

The app descriptor must be a JSON file having .moondeploy extension, whereas its companion zip archives can be created as you wish - for example, by Gradle's application plugin.

Descriptor format

The structure is fairly simple - let's see and comment an example::

{
  "DescriptorVersion": "3.0",

  "BaseURL": "https://github.com/giancosta86/test/releases/latest",
  "DescriptorFileName": "Test.moondeploy",

  "Name": "My application",
  "Version": "1.5",
  "Publisher": "Gianluca Costa",
  "Description": "A simple application to download",

  "SkipUpdateCheck": false,
  "SkipPackageLevels": 1,

  "SupportedOS": ["windows", "linux", "darwin"],

  "Packages": {
    "alpha.zip": "1.3",
    "beta.zip": ""
  },

  "CommandLine": ["bash", "bin/myApp"],

  "IconPath": "mainIcon.png",


  "OS": {
    "windows": {
      "CommandLine": ["bin\\myApp.bat"],
      "IconPath": "mainIcon.ico"
    }
  }
}

The fields can be in any order (as the descriptor is a JSON file), and can be briefly described as follows:

• DescriptorVersion: states how MoonDeploy should interpret the descriptor. For now, it should always be set to "3.0". Required

• BaseURL: the URL (HTTP or HTTPS) from which the packages will be downloaded. It generally refers to the URL where the descriptor itself will reside. Furthermore, it should be HTTPS, for enhanced security. Required

NOTE: if BaseURL has the following format:

https://github.com/USER_NAME/REPO_NAME/releases/latest

MoonDeploy will automatically call GitHub's API to resolve the actual URL of the latest descriptor for the given repository.

• DescriptorFileName: the name of the descriptor file itself, as stored in the base URL. This means that the descriptor file must be named according to its DescriptorFileName field (for security reasons). The descriptor file name must end with .moondeploy extension. Optional: if missing, App.moondeploy will be assumed.

  PLEASE, NOTE: even if you change descriptor file names with DescriptorFileName, you can only have at most one app descriptor having a given Base URL. More precisely, when running an application having the very same base url of an application already installed, MoonDeploy will stop running the newer application, showing an error. In practice, you just need to deploy app descriptors to different directories of your website - and the problem should never arise if you host your projects on GitHub! ^__^

• Name: application name. Used when resolving the application's directory and shown in desktop shortcuts as well. Required

• Version: the application version related to this descriptor. Versions have the format:

  MAJOR.MINOR.BUILD.RELEASE

  where every component is an integer number >= 0, and only MAJOR is mandatory. Required

  This field is paramount because it is checked by MoonDeploy when starting an application, to determine whether to update the app.

• Publisher: the publisher will be shown at the application's first run. Required

• Description: application's description. Employed, for example, when creating desktop shortcuts. Required

• SkipUpdateCheck: if set to true, will disable update checks when starting an app. Optional (defaults to false)

• SkipPackageLevels: when extracting a package, this parameter defines the number of directories that will be ignored in the archive tree during extraction. For example, if a tool like Gradle's application plugin creates an archive whose tree starts with the directory "APPNAME VERSION", you can avoid decompressing such root directory and only retrieve its internal files by setting SkipPackageLevels: 1. Optional (defaults to 0).

• SupportedOS: a list of strings representing the supported values of the GOOS variable. Usual values are:

• windows

• linux

• darwin (for Mac OS)

Optional: if missing, it will default to an empty list (meaning that any OS is supported).

• Packages: contains a map of package name - version elements, to be interpreted as follows:

  • package name is the actual relative path of a zip archive residing under BaseURL, usually along with the descriptor itself. Such zip files contain the application's files

  • version is a package-specific version following the format described above, or an empty string

  The Version field is important when a newer version of the application is found (that is, a descriptor having a Version newer than the Version of the descriptor saved in the app gallery at the end of the previous app execution):

  0. For every package in the new descriptor:

  > if its version is an empty string *or* if the old version is an empty string *or* if the package was not present in the old descriptor *or* the package version in the new descriptor is newer than the package version in the old descriptor, then download it
  

  0. If all the packages in the new descriptor are to be downloaded, the whole local directory containing the application files is deleted and created anew

  This field is actually optional, but it would default to an empty dictionary (therefore, it would end up deleting the application's files directory). This might be interesting to create applications not strictly relying on own files - for example, for customizations of existing applications.

• CommandLine: a string array having an executable as its first item (which might also be a program in the PATH, such as bash), followed by zero or more arguments. In the example, you can see a typical pattern working for the programs created by Gradle's application plugin. Optional (but, also considering OS settings, in the end it must be defined)

• Icon path: relative path (within the directory containing the application's files) of the application icon, consulted when creating a desktop shortcut. Optional: if the field is missing, MoonDeploy's default icon will be used.

• OS a map whose keys are GOOS values (see above) and whose values are JSON objects having the (optional) fields:

• Packages

• CommandLine

• IconPath

as described above. If one of the OS keys matches the GOOS variable, the related parameters will be merged into the descriptor, replacing the corresponding values. In the example, on Windows, CommandLine and IconPath will be set to the Windows-specific values, whereas Packages won't change. The OS field is optional

Consistency considerations

As you change the Version and/or the DescriptorVersion field of a descriptor, you can freely add/change/remove the other fields except:

• Name
• BaseURL
• DescriptorFileName

which uniquely define an application and can never be changed after publishing the very first descriptor for an app.

Migrating legacy descriptors

Legacy descriptors can be easily ported to the new format - with a caveat: in the new version of the descriptor, DescriptorFileName must be left undeclared or set to "App.moondeploy", and the descriptor file must be named App.moondeploy, for security and compatibility reasons.