We gratefully acknowledge the authors of APM 3 for their original design documentation which suggested these features, as well as the influence of the design and open-source implementation of the Red Hat Package manager, the -Debian packaging system, and PERL's CPAN in the development of the ideas +Debian packaging system, and PERL's CPAN in the development of the ideas behind this document.
A typical website will tend to offer its users a number of web-based services or applications, e.g. a bulletin board, calendaring, classified ads, etc. A website may also have underlying subsystems, such as a permissions @@ -37,7 +37,7 @@
Web-based tools for package development:
Creating new packages locally
Releasing new versions of locally-created packages
Uploading packages to a global package repository on the web
Use of these tools should be safe, i.e. installing or removing a package should never break an OpenACS installation
Web-based tools for package configuration:
The ability to change package parameter values on-line through a simple web interface.
A new ad_parameter which does not require a monolithic site-wide -parameter's file or server restarts for changes to take effect.
The ability to manage multiple package instances at the sub-site +parameter's file or server restarts for changes to take effect.
The ability to manage multiple package instances at the sub-site level.
The APM is intended for the following classes of users, which may or may not overlap:
Developers (referred to as 'the developer') use @@ -57,16 +57,16 @@ sub-site level, David configures this option in the package. When the package development is complete, David uses the APM developer UI to construct a distribution file. He assigns it a version number, 1.0, and makes the package -available for download at the OpenACS package repository.
Initial Package Installation
Annie Admin learns of David's KM system by browsing +available for download at the OpenACS package repository.
Initial Package Installation
Annie Admin learns of David's KM system by browsing the OpenACS package repository. Annie Admin uses the APM administrator UI on her system. She selects to install a package from a URL and types the URL displayed on the system. The APM automatically downloads the package. The -dependency checker notices that Patricia's Super Widget toolkit is +dependency checker notices that Patricia's Super Widget toolkit is required, so it warns Annie of this. Annie selects an option to find a package that satisfies the dependency at the OpenACS APM repository. The -APM informs Annie that it can download and install Jim's Super Widget -toolkit. Annie confirms this option. After successfully installing Jim's -toolkit, Annie proceeds to install David's KM system. The data model is +APM informs Annie that it can download and install Jim's Super Widget +toolkit. Annie confirms this option. After successfully installing Jim's +toolkit, Annie proceeds to install David's KM system. The data model is loaded and all of the files necessary for the software are installed. Because installation was successful, the package is available for use.
Since the package is available for use, its initialization routines are set to run automatically on server startup. Annie is warned that since there @@ -91,7 +91,7 @@ repository.
Sally SubAdmin asks Annie Administrator to upgrade the package using the APM UI. This upgrade supersedes the old version of KM at the site-wide level. Once Annie upgrades the package, the new version starts working immediately -in Sally's sub-site.
Procedural API
Danielle Developer wants her software to perform +in Sally's sub-site.
Procedural API
Danielle Developer wants her software to perform different actions depending on what version of another package is installed. She uses the APM procedural API to check if KM version 1.0 is installed or version 1.1. Based on the results of this procedural call, the software @@ -132,9 +132,9 @@
4.600.5 The APM will provide a facility to validate both the PGP signature and MD5 stamps information before a package install.
The user interface is a set of HTML pages that are used to drive the underlying API. It is restricted to site-wide administrators because the -actions taken here can dramatically affect the state of the running OpenACS.
The intent of the developer's interface is to enable the developer to +actions taken here can dramatically affect the state of the running OpenACS.
The intent of the developer's interface is to enable the developer to construct and maintain APM packages. It will be possible to disable the -developer's interface for production sites to help reduce the chance of +developer's interface for production sites to help reduce the chance of site failure; much of the functionality here can have cascading effects throughout the OpenACS and should not be used on a production site.
10.0 Define a package.
The developer must be able to create a new package by specifying some identifying information for the package. This includes a package name, a @@ -147,10 +147,10 @@ information for unique fields specified in the data model requirements, the package cannot be created.
20.0 Add files to a package
20.1 The developer must be able to add files to the package. This is done by copying the files into the package directory in the -host OS's file system. Files can be added at any point after package +host OS's file system. Files can be added at any point after package creation.
20.3 Once a package has been versioned and distributed, no new files should be added to the package without incrementing the version -number.
20.5 The APM's UI should facilitate the process of +number.
20.5 The APM's UI should facilitate the process of adding new files, by scanning the file system for new files automatically, and allowing the developer to confirm adding them.
20.10 The developer cannot add files to a given package via the UI that do not exist in the file system already.
20.15 Package file structure must follow a specified @@ -159,14 +159,14 @@ done in two ways.
30.1 Access the APM UI, browse the file list, and remove files.
30.1.1If a file is removed from the package list, but not from the file system, an error should be generated at package load time.
30.5 Remove the file from file system.
30.5.1 The APM UI should take note of the fact that the -file is gone and offer the developer an option to confirm the file's +file is gone and offer the developer an option to confirm the file's deletion.
40.0 Modify files in a package.
40.1 The developer should be able to modify files in the file system. The APM UI should not interfere with this.
40.5 However, if the developer modifies files containing procedural definitions, APM UI should allow a means to watch those files and automatically reload them if changed. See requirement 50.0 for more detail.
40.10 Also, although a change in files implies that the -package distribution file is out of date, it is the developer's +package distribution file is out of date, it is the developer's responsibility to update it.
4.45.0 Manage Package Dependency Information.
4.45.1 The developer should be able to specify which interfaces the package requires.
4.45.5 The developer should be able to specify which interfaces the package provides.
4.45.10 Circular dependencies are not allowed.
50.0 Watch a file
4.50.1 The developer should be able to assign a watch to @@ -201,7 +201,7 @@ but this is discouraged. In such a case, the sub-package should really be a separate package that is required by the compound package.
4.400.10 If a sub-package is required for the installation of the compound package, the compound package should have a -registered dependency on the sub-package.
The requirement of the administrator's interface is to enable the +registered dependency on the sub-package.
The requirement of the administrator's interface is to enable the administrator to install, enable, upgrade, disable, deinstall, and delete packages.
80.0 Package Enable/Disable
4.80.1 The administrator should be able mark an installed package as enabled. This means that the package is activated and its @@ -259,18 +259,18 @@ consequences throughout a site and should almost never be done.
150.0 Scan for new or modified packages
150.1 The administrator should be able to scan the file system for any changes made in any of the installed package files.
150.5 The administrator should be able to scan the file system for any newly installed packages. -
If the developer is in charge of creating packages and the administrator for installing them, then the sub-site administrator is responsible for configuring and enabling packages. In order for a package to be available for -a sub-site it must be associated with the sub-site's type specification. +a sub-site it must be associated with the sub-site's type specification. This interface is part of the sub-site /admin interface.
4.300 Creating a package instance.
4.300.1 From the sub-site /admin interface, there should be an option to view all packages available in the system as well as an option to add a package to the subsite.
4.300.5 From the "add" option, the sub-admin can select from a list of packages registered as available in the sub-site type to which the sub-site belongs.
4.300.19 Once a package instance is added, it is -available on the list of the subsite's available packages.
4.305 Configuring a package instance.
4.305.1 An automatic web interface that lists all +available on the list of the subsite's available packages.
4.305 Configuring a package instance.
4.305.1 An automatic web interface that lists all parameters with current values must be available.
4.305.5 Changing the values for the parameters is accomplished simply by submitting an HTML form.
4.310 Enabling a package instance.
4.310.1 The sub-admin should be able to enable a package with a single click. Enabling a package means that the OpenACS will serve its