Introduction

Installation

Start

General

Myself

TOPICS

Main

Configuration

System

Websites

Update

Downloads

Copyright+License

Zingoolarity Homepage

Update

Update
Remote Update Utility Overview The Zingoolarity remote update utility ("update") is a Linux console program, which allows you to update a Zingoolarity instance either to or from a remote installation. It assumes that you deal with one local installation of Zingoolarity and one remote installation of Zingoolarity. You can either push your local changes to the remote installation or you can pull remote changes to the local installation. The push is only relevant for you, if you are participating in the further development of the Zingoolarity platform itself (you are changing or extending the source code of Zingoolarity); push is comparable to an incremental deployment from a development+test environment to a production environment. The pull assumes that there is a central master web location hosting the Zingoolarity directory structure on a standard web server (e.g. Apache or NGINX) and make it thereby available to many other local installations, which obtain incremental authorative code updates from there. The update process is based on a so-called manifest file, which describes all relevant directories and files in ZML and can be edited with a plain text editor. Push Mode The push mode assumes that you make changes to the source code and supplementary files in the local installation, also optionally extending and changing the local manifest file. It then is able to automatically check the need of a directory or file update on the remote installation (based on SHA-256 hash checksums, which are calculated locally and remotely on-the-fly). Thus only changed (or new) local files are transferred to the remote installation and the entire process is much faster, compared to a brute force copy. Pull Mode The pull mode assumes that there are regular changes to the source code and supplementary files in the remote installation and that the manifest file is maintained in the remote location. The pull operation obtains the remote manifest file and verifies the need of a local update based on a SHA-256 hash checksum stored in the manifest file compared to an on-the-fly calculated checksum of the corresponding local file. The pull operation is designed with no custom processing part on the remote end (just a standard web server), so that such a setup can scale up for a 1 to many pull distribution. Let us have a look at the manifest file, as it is at the core of the entire update process. The Manifest File Every installation of Zingoolarity contains a file called manifest.zml. It looks like this (we only show the first couple of lines to be able to explain how it works; the real file is about 200 lines long): [url]https://www.zingoolarity.com[/url] [token]859c8a36926c4b8e9a3db5b9440612d7[/token] [item] [name]LICENSE.txt[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]README.txt[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]api.go[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset[/name] [type]dir[/type] [mode]create[/mode] [/item] [item] [name]asset/Amaranth-Regular.ttf[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/Lato-Regular.ttf[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/Merriweather-Regular.ttf[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/Roboto-Regular.ttf[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/TravelingTypewriter.ttf[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/Ubuntu-Regular.ttf[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/about.png[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/act.png[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/back.png[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/background.jpg[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/cancel.png[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/check.png[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/clear.png[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/click.mp3[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/click2.mp3[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/click3.mp3[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/click4.mp3[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/click5.mp3[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/click6.mp3[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/close.png[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/code.png[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/context.png[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/cut.png[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/delete.png[/name] [type]file[/type] [mode]update[/mode] [/item] [item] [name]asset/detail.png[/name] [type]file[/type] [mode]update[/mode] [/item] ... The ZML tag [url] defines the address of the remote installation and the ZML tag [token] defines the secret certificate of a remote user, who has the system property set to true (as push updating is a sensitive system-related function). After these two tags, an unlimited number of [item] tags can follow. They define either directories or files, which are officially part of Zingoolarity. The [name] tag inside the [item] tag defines the relative directory path of a directory or file inside the Zingoolarity installation directory. The [type] tag defines whether the item is a directory (dir) or a file (file). The [mode] tag defines the update mode (or in other words what to do). The following modes are available, depending on the type of the item: Directory [type]dir[/type] create (create a directory if it does not exist yet) destroy (unconditionally remove a directory and everything below) refresh (refreshes an entire directory and everything below) none (take no action) File [type]file[/type] update (overwrite a file if it needs updating) updatelive (overwrite a file if it needs updating, even if it is in use) delete (unconditionally delete a file) none (take no action) The destroy (directory) and delete (file) modes allow you to remove deprecated directories or files on the remote installation. These are usually only needed to run once (e.g. if you want to remove a source code file which is no longer part of Zingoolarity or if you want to remove a directory completely and force replacing it with a completely new content). Invoking "update" You can start the Zingoolarity remote update utility by typing the following inside of your local Zingoolarity installation directory: ./update If no parameters are given, the usage will be displayed: zingoolarity.update(main) 2024-10-01 13:02:46: update v1.0 2024-08-09 (Zingoolarity Remote Update Utility) zingoolarity.update(main) 2024-10-01 13:02:46: (using configuration in zingoolarity.ini) zingoolarity.update(main) 2024-10-01 13:02:46: usage: ./update [help,build,hash,push,trypush,pull,restart,shutdown] ([url]) [manifestfile] Building a Manifest File from Scratch "update" allows you to build a new manifest file from scratch (which will include ALL directories and files inside of the Zingoolarity installation directory). To do so, you have to enter a command like the following: ./update build manifestdemo.zml The output will be the following: zingoolarity.update(main) 2024-05-14 16:52:23: update v1.0 2024-08-09 (Zingoolarity Remote Update Utility) zingoolarity.update(main) 2024-05-14 16:52:23: (using configuration in zingoolarity.ini) zingoolarity.update(main) 2024-05-14 16:52:23: collecting file and directory information zingoolarity.update(main) 2024-05-14 16:52:23: writing manifest file: manifestdemo.zml zingoolarity.update(main) 2024-05-14 16:52:23: manifest file successfully compiled: manifestdemo.zml The produced manifestdemo.zml file will contain all directories and files below the local Zingoolarity installation directory, transformed into [item] tags. You can now edit the manifestdemo.zml file with a plain text editor and remove everything, which does not belong to an official Zingoolarity installation (and set the [url] and [token] tags to the correct values for your remote installation). Pushing an Update to the Remote Installation Now you can make changes to the local installation and also modify the manifest file if necessary. If you want to update your remote installation, you enter the following command: ./update push manifestdemo.zml This will connect to your remote installation, go through your manifest file item-by-item, will check the need for updating and if necessary will act according to the specified modes. The update is a verbose operation; each and every action taken will be printed to the screen. Performing a Push Dry Run If you just want to test whether the push operation works and which actions on files and directories have to be taken, you can use the trypush command instead of the push command. This looks and feels like the real push, but will actually not perform the update on the remote side. Adding Hashes to the Manifest File The push operation does not require this step, as the local and remote hashes are calculated on-the-fly. In contrast, the pull operation requires the pre-calculated hash codes as part of the manifest file, as it is designed to scale up to many clients and as it only requires a remote static web server to function. You can add the hashes in the format of a [hash]...[/hash] tag to a previously generated or manually created manifest file with the following command: ./update hash manifestdemo.zml This command will parse all local files mentioned in the manifest file and will calculate the hashes, which are then stored in a 2nd file with an appended 2 (In the above example this would be the file manifestdemo.zml2). This 2nd manifest file is the one you require for a pull update. Pulling an Update from a Remote Location To pull an update from a central authorative location, you can enter the following command: ./update pull https://update.zingoolarity.com manifestdemo.zml2 This will obtain the specified manifest file from the specified remote location and perform the update based on the content of the manifest file. Restarting the Remote Instance After a successful update, you usually need to restart the remote (or local) instance to pick up the newest executable. This can be achieved by entering the following command while connected to the instance which needs to be restarted: ./update restart manifestdemo.zml Your instance will restart (which usually takes a couple of seconds). Stopping the Remote Instance If (for whatever reason) you need to shutdown the remote (or local) instance of Zingoolarity, you can do so with the following command: ./update shutdown manifestdemo.zml The Zingoolarity process will stop and you will need operating system access to restart the process again at a later point-in-time. This is only helpful in emergency situations (e.g. the occurrence of a security issue).

Remote Update Utility

Overview

The Zingoolarity remote update utility ("update") is a Linux console program, which allows you to update a Zingoolarity instance either to or from a remote installation.

It assumes that you deal with one local installation of Zingoolarity and one remote installation of Zingoolarity.

You can either push your local changes to the remote installation or you can pull remote changes to the local installation.

The push is only relevant for you, if you are participating in the further development of the Zingoolarity platform itself (you are changing or extending the source code of Zingoolarity); push is comparable to an incremental deployment from a development+test environment to a production environment.

The pull assumes that there is a central master web location hosting the Zingoolarity directory structure on a standard web server (e.g. Apache or NGINX) and make it thereby available to many other local installations, which obtain incremental authorative code updates from there.

The update process is based on a so-called manifest file, which describes all relevant directories and files in ZML and can be edited with a plain text editor.

Push Mode

The push mode assumes that you make changes to the source code and supplementary files in the local installation, also optionally extending and changing the local manifest file.

It then is able to automatically check the need of a directory or file update on the remote installation (based on SHA-256 hash checksums, which are calculated locally and remotely on-the-fly).

Thus only changed (or new) local files are transferred to the remote installation and the entire process is much faster, compared to a brute force copy.

Pull Mode

The pull mode assumes that there are regular changes to the source code and supplementary files in the remote installation and that the manifest file is maintained in the remote location.

The pull operation obtains the remote manifest file and verifies the need of a local update based on a SHA-256 hash checksum stored in the manifest file compared to an on-the-fly calculated checksum of the corresponding local file.

The pull operation is designed with no custom processing part on the remote end (just a standard web server), so that such a setup can scale up for a 1 to many pull distribution.

Let us have a look at the manifest file, as it is at the core of the entire update process.

The Manifest File

Every installation of Zingoolarity contains a file called manifest.zml.
It looks like this (we only show the first couple of lines to be able to explain how it works; the real file is about 200 lines long):

[url]https://www.zingoolarity.com[/url]
[token]859c8a36926c4b8e9a3db5b9440612d7[/token]

[item] [name]LICENSE.txt[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]README.txt[/name] [type]file[/type] [mode]update[/mode] [/item]

[item] [name]api.go[/name] [type]file[/type] [mode]update[/mode] [/item]

[item] [name]asset[/name] [type]dir[/type] [mode]create[/mode] [/item]
[item] [name]asset/Amaranth-Regular.ttf[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/Lato-Regular.ttf[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/Merriweather-Regular.ttf[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/Roboto-Regular.ttf[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/TravelingTypewriter.ttf[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/Ubuntu-Regular.ttf[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/about.png[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/act.png[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/back.png[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/background.jpg[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/cancel.png[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/check.png[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/clear.png[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/click.mp3[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/click2.mp3[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/click3.mp3[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/click4.mp3[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/click5.mp3[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/click6.mp3[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/close.png[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/code.png[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/context.png[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/cut.png[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/delete.png[/name] [type]file[/type] [mode]update[/mode] [/item]
[item] [name]asset/detail.png[/name] [type]file[/type] [mode]update[/mode] [/item]
...

The ZML tag [url] defines the address of the remote installation and the ZML tag [token] defines the secret certificate of a remote user, who has the system property set to true (as push updating is a sensitive system-related function).

After these two tags, an unlimited number of [item] tags can follow.

They define either directories or files, which are officially part of Zingoolarity.

The [name] tag inside the [item] tag defines the relative directory path of a directory or file inside the Zingoolarity installation directory.

The [type] tag defines whether the item is a directory (dir) or a file (file).

The [mode] tag defines the update mode (or in other words what to do).

The following modes are available, depending on the type of the item:

Directory [type]dir[/type]
create (create a directory if it does not exist yet)
destroy (unconditionally remove a directory and everything below)
refresh (refreshes an entire directory and everything below)
none (take no action)

File [type]file[/type]
update (overwrite a file if it needs updating)
updatelive (overwrite a file if it needs updating, even if it is in use)
delete (unconditionally delete a file)
none (take no action)

The destroy (directory) and delete (file) modes allow you to remove deprecated directories or files on the remote installation.

These are usually only needed to run once (e.g. if you want to remove a source code file which is no longer part of Zingoolarity or if you want to remove a directory completely and force replacing it with a completely new content).

Invoking "update"

You can start the Zingoolarity remote update utility by typing the following inside of your local Zingoolarity installation directory:

./update

If no parameters are given, the usage will be displayed:

zingoolarity.update(main) 2024-10-01 13:02:46: update v1.0 2024-08-09 (Zingoolarity Remote Update Utility)
zingoolarity.update(main) 2024-10-01 13:02:46: (using configuration in zingoolarity.ini)
zingoolarity.update(main) 2024-10-01 13:02:46: usage: ./update [help,build,hash,push,trypush,pull,restart,shutdown] ([url]) [manifestfile]

Building a Manifest File from Scratch

"update" allows you to build a new manifest file from scratch (which will include ALL directories and files inside of the Zingoolarity installation directory).

To do so, you have to enter a command like the following:

./update build manifestdemo.zml

The output will be the following:

zingoolarity.update(main) 2024-05-14 16:52:23: update v1.0 2024-08-09 (Zingoolarity Remote Update Utility)
zingoolarity.update(main) 2024-05-14 16:52:23: (using configuration in zingoolarity.ini)
zingoolarity.update(main) 2024-05-14 16:52:23: collecting file and directory information
zingoolarity.update(main) 2024-05-14 16:52:23: writing manifest file: manifestdemo.zml
zingoolarity.update(main) 2024-05-14 16:52:23: manifest file successfully compiled: manifestdemo.zml

The produced manifestdemo.zml file will contain all directories and files below the local Zingoolarity installation directory, transformed into [item] tags.

You can now edit the manifestdemo.zml file with a plain text editor and remove everything, which does not belong to an official Zingoolarity installation (and set the [url] and [token] tags to the correct values for your remote installation).

Pushing an Update to the Remote Installation

Now you can make changes to the local installation and also modify the manifest file if necessary.

If you want to update your remote installation, you enter the following command:

./update push manifestdemo.zml

This will connect to your remote installation, go through your manifest file item-by-item, will check the need for updating and if necessary will act according to the specified modes.

The update is a verbose operation; each and every action taken will be printed to the screen.

Performing a Push Dry Run

If you just want to test whether the push operation works and which actions on files and directories have to be taken, you can use the trypush command instead of the push command.

This looks and feels like the real push, but will actually not perform the update on the remote side.

Adding Hashes to the Manifest File

The push operation does not require this step, as the local and remote hashes are calculated on-the-fly.

In contrast, the pull operation requires the pre-calculated hash codes as part of the manifest file, as it is designed to scale up to many clients and as it only requires a remote static web server to function.

You can add the hashes in the format of a [hash]...[/hash] tag to a previously generated or manually created manifest file with the following command:

./update hash manifestdemo.zml

This command will parse all local files mentioned in the manifest file and will calculate the hashes, which are then stored in a 2nd file with an appended 2 (In the above example this would be the file manifestdemo.zml2).

This 2nd manifest file is the one you require for a pull update.

Pulling an Update from a Remote Location

To pull an update from a central authorative location, you can enter the following command:

./update pull https://update.zingoolarity.com manifestdemo.zml2

This will obtain the specified manifest file from the specified remote location and perform the update based on the content of the manifest file.

Restarting the Remote Instance

After a successful update, you usually need to restart the remote (or local) instance to pick up the newest executable.

This can be achieved by entering the following command while connected to the instance which needs to be restarted:

./update restart manifestdemo.zml

Your instance will restart (which usually takes a couple of seconds).

Stopping the Remote Instance

If (for whatever reason) you need to shutdown the remote (or local) instance of Zingoolarity, you can do so with the following command:

./update shutdown manifestdemo.zml

The Zingoolarity process will stop and you will need operating system access to restart the process again at a later point-in-time.

This is only helpful in emergency situations (e.g. the occurrence of a security issue).