Getting started with ChiffonUpdater

This page will teach you how to configure correctly a simple infrastructure with ChiffonUpdater

First, grab a copy of the toolkit here:

Now, let's learn important terminology

• Project (also ChiffonUpdater Project or CUPJ): This is the project file used by the toolkit which contains all the informations about every registered products as well as various settings.
  A software editor should usually only need one cupj file. The project file doesn't need to be public and it is even recommended to keep it private.
• Product: This usually represents one software that the software editor distributes.
• Feature: A product have at least one feature. A feature is a special set of file that a product can have. For instance, a video game could have a feature called shared containing shared files, a feature called zombies containing files for a special zombie game mode and a feature called bonus which could be a paid DLC.
  Please note that the updating software doesn't support rolling back products which modified their feature set. If you install an update then add a new feature, you won't be able to rollback.
• Reporting file: This is the file which is considered as the main file of the project and which uses the external library to register itself to the products list.
• External library: This is a piece of software generated by the Toolkit which should be unique to each software editor and which is included in every products to register itself to the local product list.
• Local product list: A local list on the end-user computer which contains the location where the different products are installed. Without this file, it is impossible to detect products to update.
• Source folder: This is the folder in which every binaries should be found.
• BinPack: A set of binary components used by ChiffonUpdater.
• Backend folder: This is the folder that should be hosted on a server

Selecting a source folder

At this point you will be prompted to select a source folder. For this, you can create an empty source folder (it will be filled during the different steps).
This folder has no reason of being public, but it could be shared in an intranet.

Creating a project

At this point you learn some important terminology, you can open the toolkit. The first thing you want to do is create a project. This project will contain your products.
Creating a new project can be done by reaching the toolbar, and going into File > New...

At this point, informations about the project are asked to you: in which folder will be the local product list and other core files of ChiffonUpdater. You have two choices:

• Use a global path which will be independant of the system: This path should not rely on system specific environment variables.
• Use a system dependant path: You can rely on system environment variables.

In both cases, you can surround your variable with the dollar sign (example: $variable$) to replace it with a Java system property (a small list can be found on this documentation page)
You can also surround it with the percent sign (example: %variable%) to replace it with an OS-specific environment variable

Choosing the right path can be though sometimes. The best path is a folder named Updates under a folder shared by all the softwares of the editor.

Preparing products

With the help of the toolkit, you can now generate an external library that you will have to integrate into your products. For this, you must go to Project > Generate external library.
You will be prompted for a BinPack selection, consider choosing GitHub (if you want to update the cached binaries) or Cached (if the binaries are known to be already up-to-date).
You will afterwards be prompted for a path where to save the external library. Once you have this external library, integrate it in your products according to the technical documentation guide for integrating the external library.

Registring products

You now need to register products: this requires a little bit of planning.
You can also choose not to use a source folder but this is not supported by this tutorial page.

Preparing the structure of products

This step entirely consists on gathering informations. You will need to know what is the version in which the external library can be integrated (this usually will be the next version of the product).
Then you have to think about how will the product be divided. If it is not needed to divide the product in different set of files, then you must put everything into one feature that you would idealy call main.

Registering the product

You can now register a new product (Project > Register new product or right click on the project icon then Register new product)
Fill in the blank corresponding to the product name, and add the different features required by the product.
Once this is done, a new entry will appear in the tree: this is your product.
You will now have to add a new version entry corresponding to the first version of the program embedding the ChiffonUpdater external library (or another version if you are here because you are registering a new update).
To do so, right click on your product and click Add version.
You can also choose a version description that will appear in the update package or the website.
Note that each version you create will be set as the latest: their version rank will be the highest. You can increase and decrease the version rank.

This task must be done for every products you want to register into the system.

Completing the source folder

Once you entered all the informations, you can fill the source folder. If you haven't disabled the automatic source folder structure generation,
the source folder should be organised like this (in this example, multiple versions are included):

root of the source folder
            |
            |
            +-- Product A  -+- v1.0 -+- main 
            |               |        \- bonus
            |               |
            |               \- v2.0 -+- main 
            |                        \- bonus
            |
            \-- Product B  -+- v1.0 -+- main 
                            |        \- bonus
                            |
                            +- v2.0 -+- main 
                            |        \- bonus
                            |
                            \- v3.0 -+- main 
                                     \- bonus
                                     
            

You can also add other files such as EULA or custom modules at the root of the source folder, a product folder or a version folder, but avoid putting content in a feature folder as it contains the binary files of your program and it might be interpreted as part of the program.

You will have to fill now the different folders with the different binaries of each product (this includes the external library file). Once this is done,
you will now need to navigate to the different features of the versions of each products and press Auto add files from folder which will save the hash of the different files.

Preparing the website

First, you will have to think about two locations:

• A location which can serve a static web site in HTTP or HTTPS (for hosting the website)
• A location which can act as a download server in HTTP or HTTPS (for hosting the backend folder)

The two locations can be on the same server, but avoid putting the backend folder in the website folder and the website folder in the backend folder.
A recommended structure could be (as an example):

https://updates...........com/web (for the website) and https://updates...........com/updates (for the backend)

Once you know these two locations, create a backend folder (that can be accessed by the server or that you will update manually on the server, for example through FTP).
In the toolkit, move to the Website section (which should appear as Disconnected) for now. You can choose here if you want an update catalog or not. The update catalog would allow administrators to run offline updates.

In Backend URL, write the URL which will be used to access the backend folder through (https://updates...........fr/updates/ in the example, DO NOT FORGET THE TRAILING SLASH!)

Once this is done, right-click on the website and click Create frontend configuration file. This file contains useful informations for the website such as where to find the backend.
If you change the backend URL, you will have to regenerate this file.

This file must replace the res/js/config/webcucfg.js file in the website folder..

We now have a final step which consists of synchronizing the backend folder. To do so, you must first tell the tookit where can it modify the folder. To do so, right-click on Website and press Connect backend folder, then choose the local path to the backend folder.
You now only need to right-click on Website and press Synchronize backend files, and go through the different steps.

Congrats, you now have a working ChiffonUpdater update infrastructure running and accessible!

While this tutorial covered what to do to get a running infrastructure, don't forget to check the technical documentation for many more information