Documentation

A package is basically a tar.gz file containing a web application and some installation scripts. To build a package, at least the following files must be provided: . build.py: a definition file that contains the information required to download and build the package. . description.py: a definition file that provides the information about the package (name, release, revision, description, supported installation modes, etc). . installer.py: initial installation script on which Cherokee-Admin relies once it has downloaded the package to be installed. . Additionally, delta files to apply patches can be provided (to use while building the package), as well as other auxiliary installer files to be used by the main installer.py script. Also it is recommended to provide a file with notes about the installer or detailing a QA procedur to ensure the quality of the package.

Lets detail the structure of both essential files and then we can proceed with some more specifics.

This must provide all the details required to successfully download, patch, and build the installer. The building change is actually quite sophisticated and will cache things whenever possible: it will not attempt to re-download source files, or even rebuild the package if .build.py

You can see several interesting properties on this file, which deserve more specific descriptions.

List of script dependencies. Basically intended to include the modules provided under the common directory. These are modules that take care of common functionality used extensively throughout all the installers.

At the moment of writing, it contains the following modules.

This is the list of scripts that must be packed with your installer (besides the ones specified as dependencies. In this list you can also specify files from other installers, which is the case when packing extended versions and you want to have a unique source to maintain when upgrading releases.

This is the list of directories that should be included in the package. It is usually a good idea to specify the names after they have been renamed by the building script, so that you can avoid the need of having to rename directories manually every time you upgrade your package. More on this on the following entry.

List of files that have to be downloaded from third party repositories. It is provided as a list of dictionaries with several keys, which globally allow you to define precisely what to download and where to put it. It also includes the directions required to apply patches and rename files/directories on demand, which is a good idea since by setting the directory names you can isolate the build script from the installer script.

Each entry is a dictionary. Providing the dir and url elements is mandatory. All the rest are optional.

As has been mentioned, this file provides information about the package. The repository has to be indexed, and this is the source of such data.

Everything is pretty self descriptive. The software dictionary should suffice to display information about the package within Cherokee Admin. It will be automatically put in place according to the category tag. Look for the one that better suits your app and use it, or create a new category if necessary.

The installation properties define supported installation modes, supported Operating Systems, and supported database engines. These must be chosen among the following lists.

After downloading and decompressing a package, Cherokee Admin hands over the control to this script. It basically provides a configuration template, and follows the chain on installation stages until the common final installation stage is reached. Once this happens, Cherokee Admin will save and apply the configuration if possible, or will notify if pending changes remained before the installation so the step can be performed manually.

Control is handed over by visiting a local URL that is used as entry point to the installer, and is returned when, upon completion, the installer visits another URL which is the exit point. In the middle, the chain of URLs must be published by the installer itself, that also has to establish the control flow between them.

You are advised to make extensive use of the logging capabilities provided by market.Install_Log, so that it is easier to develop package-installers and report bugs if necessary.

Have a look at the hello_world installer in the repository to see a thoroughly commented example. Here is an excerpt of a very basic example.

An overview of each section follows.

This part is where you would import all the accessory modules into your current name space. Those are the ones with common functionality, or the ones you’ve added to the package besides build.py and installer.py. Note that absolute paths are specified on each import.

====Batch commands: POST_UNPACK_COMMANDS This is a list of command entries. If this property is present in the installer script, the entries will be executed sequentially right after downloading and unpacking the application. When an error occurs the problem is notified within the installation screen. Otherwise, execution proceeds towards the first defined stage.

The list of POST_UNPACK_COMMANDS is comprised of command entries that will be processed through an instance of market.CommandProgress.CommandProgress. Please refer to it later on this document for the specifics.

You need to know market.Install.Install_Stage. Every installation stage inherits from this class, and will render the contents that need be displayed in the installation dialogs.

The flow is determined by the mapped URLs/classes that are published by CTK in each installer.

The entry point is market.Install.URL_INSTALL_SETUP_EXTERNAL. An hypothetical installer that wants to handle checks for dependencies through a class called Precondition that inherits from market.Install.Install_Stage, would map the URL to the class with the following code:

Each stage must redirect the flow to the next URL, and each URL must be mapped to an Install_Stage with an analogous syntax. This mapping applies to every stage except the last one. Upon successful completion, the last Install_Stage should redirect the flow towards the standard exit point, market.Install.URL_INSTALL_DONE, which is already mapped

The build.py script can specify what patches have to be applied on build-time. Those are only applied if the entry specified in build.py is downloaded, so the caching mechanism for downloads and built packages remains consistent.

It is recommended that these patches are generated using diff -rcu to maintain uniformity on the repositories and to provide context to the patches, possibly remaining valid after package upgrades.

Some functionality is provided directly ith Cherokee Admin, which is what will be described in the following lines. Also, there are a series of common elements that can be reused by different installer (target selection, database management, handling PHP and PHP modules, etc.). As was mentioned before, such elements are encapsulated as independent modules distributed under the common directory, and are usually well comment, so don’t forget to review them before you begin working on your custom installers.

popen.popen_sync is a function that provides a subset of the functionality of the subprocess.Popen class, but it does so consistently along all Python 2.x versions. Installers frequently need to execute command-line tasks, and this is the function that should be used. It accepts the following arguments.

The most important function is market.Install_Log.log, which should be used extensively to log absolutely everything performed during an installation. File creation, task execution, and database modifications are logged in a file called install.log in the application’s directory.

When maintenance tasks are launched to completely erase orphan or broken installations, this file is parsed to revert the modifications done to your system.

It is also useful to log everything to ease up the troubleshooting process if anything goes wrong.

The most relevant class is market.CommandProgress.CommandProgress.

This class provides a way to process time consuming tasks in a sequential manner, without having to worry about the connection timing out. It is a CTK widget, and as such can be added to an existing container and will begin execution once it has been rendered. Provided a list of command entries, these will be executed sequentialy, after which the control flow will proceed to the URL specified when CommandProgress object was instanced. During execution, it will display a progress bar, and additionaly the command being executed or a provided description.

Command entries are dictionaries with the following arguments, where specifying either a "command" or a "function" argument is mandatory.

Additional replacement macros can be specified when the CommandProgress in instanced manually, which is always except for the one that processes the POST_UNPACK_COMMANDS property. It is as simple as setting the macros as properties of the CommandProgress object.

The class market.Util.InstructionBox is used extensively, particularly by stages that check for preconditions that need be fulfilled in order to complete the installation of an application.

It is a CTK widget used to display instructions to install software, tailored specifically to the users’ platform. It must be instanced with a mandatory note, such as "PHP not detected in your system.", and a dictionary (or list of dictionaries, for multi-message instructions) with messages for each platform.

If instanced, the InstructionBox will determine which entry is apropriate for the user’s system, and show only that one (or fall through to the default entry and show that one if nothing more specific is found).