| Prev | Chapter�13.�Kernel Documentation | Next |
|---|
+
The following is a requirements document for the OpenACS Package Manager (APM), version 4.0 (APM4). APM4 offers a superset of APM v3.3 functionality with the following specific enhancements:
A public procedural API. (v 3.3 only has web-based UI)
Support for dependency checking.
Support for compound packages (to support installation chaining).
Support for on-line parameter setting.
Support for sub-site level configuration (requires revised ad_parameter and /admin pages at sub-site level; deprecation of site-wide parameter @@ -13,7 +12,7 @@ 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 -behind this document.
A typical website will tend to offer its users a number of web-based +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 system, content management system, etc. For such applications and subsystem @@ -27,7 +26,7 @@ OpenACS sites.
In general terms, a package is a unit of software that serves a single well-defined purpose. The OpenACS Package Manager (APM) provides a mechanism for packaging, installing, and configuring OpenACS software in a consistent, -user-friendly, and subsite-aware manner.
The OpenACS Package Manager (APM) consists of:
A standard format for APM packages including:
Version numbering, independent of any other package and the OpenACS as a whole
Specification of the package interface
Specification of dependencies on other packages (if any)
Attribution (who wrote it) and ownership (who maintains it)
Web-based tools for package management:
Obtaining packages from a remote distribution point
Installing packages, if and only if:
All prerequisite packages are installed
No conflicts will be created by the installation
Configuring packages (obsoleting the monolithic OpenACS configuration @@ -39,7 +38,7 @@ 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 -level.
The APM is intended for the following classes of users, which may or may not overlap:
Developers (referred to as 'the developer') use the APM to create a software package for distribution and use the procedural @@ -96,21 +95,21 @@ 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 -exhibits different behavior.
4.500.0 Package Identification +exhibits different behavior.
4.500.0 Package Identification (All of these items are entered by the developer using the developer UI.)
4.500.1 A human readable package key that is guaranteed to be unique to the local OpenACS site must be maintained by the APM. For -example, "apm."
4.500.5 A package id (primary key) that is guaranteed to +example, "apm."
4.500.5 A package id (primary key) that is guaranteed to be unique to the local site must be maintained by the APM. For example, -"25."
4.500.10 A package URL that is guaranteed to be unique +"25."
4.500.10 A package URL that is guaranteed to be unique across all sites must be maintained by the APM. The package URL should point to a server that allows download of the latest version of the package. For -example, "http://openacs.org/software." +example, "http://openacs.org/software."
4.505.0 Version Identification (All of these items are entered by the developer using the developer UI.)
4.505.1 A version id (primary key) that is guaranteed to be unique to the local site must be maintained by the APM.
4.505.5 A version URL that is guaranteed to be unique across all sites must be maintained by the APM. The version URL should point to a server that allows download of a specific version of the package. -
The API for APM v3 is explicitly a private API. However, it would be useful to obtain information from the APM through a procedural API. Implementing the API specified below is quite easy given that there are pages that already do all of the below in raw SQL.
4.400.0 Packages Status Predicates
4.400.1 Given defining information such as a package URL, @@ -124,16 +123,16 @@ admins. The subsite parameter can be set to be non-persistent (but default is to survive server restarts). The subsite parameter can also be set to only take effect after a server restart (default is immediate).
4.415.5 Parameters for a given subsite and package can be -returned by the system API.
Provisions will be made to assure that packages are securely identified.
4.600.1 Each package will have a PGP signature and there will be MD5 time stamps for each file within the package.
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 site failure; much of the functionality here can have cascading effects @@ -155,7 +154,7 @@ 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 -convention. Please see the design +convention. Please see the design document for what we do currently.
30.0 Remove files from a package
The developer must be able to remove files from a package. This can be 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 @@ -184,7 +183,7 @@ XML specification to disk.
70.5 The developer should be able to request the current XML specification for all installed, locally generated packages.
130.0 Distribution file generation
130.1 The developer should be able to generate a .APM distribution file for the package with just one click.
130.5 Generating a distribution file implies doing an -"up-to-date" check on all of the files. If any of the files have +"up-to-date" check on all of the files. If any of the files have changed since package installation, then a new version of the package is created. @@ -197,12 +196,12 @@ allow for separation of optional and required components from the installation as well as better organization of files once installed. For example, all documentation for the community-core can be packages as -community-core-doc.apm. It is legal to include sub-packages with +community-core-doc.apm. It is legal to include sub-packages with dependencies that are not satisfied by the packages in the compound package, 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.200.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 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 @@ -260,15 +259,15 @@ 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. 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 +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 @@ -284,7 +283,7 @@ only the package instance, but any and all content associated with it. It is questionable whether this option should even be available due to its drastic consequences. Reviewer comments appreciated. -
Despite the fact that requirements are meant to be design/implementation neutral, the following thoughts were in our head when specifying these requirements. You must be familiar with the new object design for this to be comprehensible.
When a package is installed system-wide, a corresponding acs_object_type @@ -293,4 +292,4 @@ are set using the acs_attribute_values table. The automatic web interface for setting package parameters should be one and the same with the interface for setting acs object attribute values. Consequently, the implementation of -these features should be quite straightforward.
| Document Revision # | Action Taken, Notes | When? | By Whom? |
| 0.1 | Creation | 8/10/2000 | Bryan Quinn, Todd Nightingale |
| � | Reviewed | 8/11/2000 | John Prevost, Mark Thomas, and Pete Su |
| 0.2 | Revised and updated | 8/12/2000 | Bryan Quinn |
| 0.3 | Reviewed, revised, and updated - conforms to requirements template. | 8/18/2000 | Kai Wu |
| 0.4 | Minor edits before ACS 4 Beta. | 9/30/2000 | Kai Wu |
| Document Revision # | Action Taken, Notes | When? | By Whom? |
| 0.1 | Creation | 8/10/2000 | Bryan Quinn, Todd Nightingale |
| � | Reviewed | 8/11/2000 | John Prevost, Mark Thomas, and Pete Su |
| 0.2 | Revised and updated | 8/12/2000 | Bryan Quinn |
| 0.3 | Reviewed, revised, and updated - conforms to requirements template. | 8/18/2000 | Kai Wu |
| 0.4 | Minor edits before ACS 4 Beta. | 9/30/2000 | Kai Wu |
