################################################# # # # BUGGER # # Automated Updates and Installs # # Design Document # # # # Document Date: 25 March 2010 # # # ################################################# Contents --------- - Aim - Implementation - Design - Updates - Auto Install - Overall Design - Table Design - Updates - Install - Server Responses - To Do - Example Use - Intended Use Aim ---- 1) To be able to enable auto-update in various projects, 2) To be able to distribute a small script that will automatically download, install and configure a project. Implementation --------------- It seems logical to create the server-side functionality in BUGGER. Once this is done, client scripts can be written as required so long as a detailed API is published. Design ------- Updates -------- When an update is created, an installation script should be created and registered in BUGGER. The client should provide a project ID and a version ID (it's current version) The system should query the relevant table (to be created) and return details of the location of the installation script (if an update exists). The script will then be run by the client, once it has completed, it should check for updates again in case the client is several versions out of date. Although the implementation of the installation scripts will vary by project and update, a basic API should be published to allow easy client creation. Auto Install ------------- Auto install functionality will allow distribution of a script that will contain specific configuration for an intended use, the script will then use this API to install the program itself. Full releases should be registered in the relevant table (to be created) with an accompanying version number. Patch releases should be restricted to the update function. An installation script should also be registered for each release (it may be possible to use the same script for multiple releases so long as the process doesn't change). The client script may of course use a custom installation method, the API should allow for this, and an indicator should be added to the relevant table to allow this to be inhibited if a release requires a specific installation method. A clear API should be published detailing request methods and example client implementations. Overall Design --------------- It is expected that the server-side implementation should use a single CGI script to process either type of request. The update and install functionality would of course be consigned to their own functions. Obviously the script should be designed to be easily scalable so that it can process a multitude of different requests from various clients. The only restiction in this respect should be that imposed by the web server's configuration. Logically, the release notification page of BUGGER should be adapted to automatically populate the relevant tables. Table Design ------------- Updates -------- Table name: AutoUpdate Column | Name 1 | Update ID (Primary Key) 2 | Project ID 3 | Version 4 | Install Script Location 5 | Tarball Location 6 | Alpha/Beta/Release 7 | Date/Time Committed 8 | Submitted by (user) 9 | Checksum of Tarball 10 | Updates Version (Old version) The Version Number submitted by the client will be compared against the value stored in Column 10 to ensure that updates are applied in the correct order. Auto Install ------------- Table Name: AutoInstall Column | Name 1 | RecordID (Primary Key) 2 | ProjectID 3 | Tarball Location 4 | Install Script Location 5 | Allow Custom Install Script 6 | Version 7 | Date/Time Submitted 8 | Submitted by (User) 9 | Publish (Y/N) 10 | Tarball Checksum 11 | Project License Column 5 should contain either Y or N. If set to N then the system will note that Custom Install scripts will not work. Any client that adheres to the API will then run the provided install script instead of their customisation. If this is not suitable for their needs, the client should exit. Column 9 should contain either Y or N. If set to Y only clients configured to install Testing versions will be able to retrieve the record. Each project can have a maximum of two records in this table (one set as Publish, one Not). If more records exist, the server will log an error and return the first matching record. Server Responses ----------------- The server will return data in the following format; VARIABLENAME="$VALUE" with one variable per line. These variables should be published in the API for easy client implementation. In the case of an error the script should return; ERROR: Error Description (and code) and should also log the error (table to be created) for the admin to review later. To Do ------ - Create necessary tables - Create server-side script - Test script - Create BUGGER Management Pages - Test Pages - Write, check and publish API's - Write example client scripts based on API Example Use ------------ The project 'Document Library' relies on Claims_DB and also requires a specific FTP & Apache configuration. A document can be created detailing how to install and configure the project, but some may find it overly complex and not use the software as a result. Instead, a small shell script could be published, this would use the Install API to retrieve and install Claims_DB. It would then create the configuration files & set permissions. It would then retrieve & install Proftpd & Apache, set them to run at boot and customise the configuration files. It could then retrieve Document Library, install it with the desired configuration, ensure everything is running, check for updates for the newly installed version, then exit. The script could prompt the use for variables (i.e. where would you like to install Claims_DB?) or use pre-defined values. Intended Use ------------- Installation scripts should not replace good quality documentation. Instead they should be a convenient alternative for users. If the install document is created before the script, it should be a good resource for building the shell script. ################################################# # # # DOCUMENT END # # # # Copyright 2010 Ben Tasker # # Released under GNU GPL V3 # # http://benscomputer.no-ip.org/LICENSE3 # # # #################################################