Index: openacs-4/packages/acs-core-docs/www/apm-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-requirements.html,v diff -u -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/apm-requirements.html 20 Aug 2003 16:20:16 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/apm-requirements.html 14 Oct 2003 11:02:57 -0000 1.12 @@ -1,9 +1,8 @@ - -OpenACS 5.0.0d Package Manager Requirements

OpenACS 5.0.0d Package Manager Requirements

+OpenACS 5.0.0a1 Package Manager Requirements

OpenACS 5.0.0a1 Package Manager Requirements

by Bryan Quinn and Todd Nightingale
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Introduction

The following is a requirements document for the OpenACS Package Manager +

Introduction

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.

Vision Statement

A typical website will tend to offer its users a number of web-based +behind this document.

Vision Statement

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.

System Overview

+user-friendly, and subsite-aware manner.

System Overview

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:

      1. All prerequisite packages are installed

      2. 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.

Use-cases and User-scenarios

+level.

Use-cases and User-scenarios

The APM is intended for the following classes of users, which may or may not overlap:

  1. 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.

Requirements: Data Model

  • 4.500.0 Package Identification +exhibits different behavior.

Requirements: Data Model

  • 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. -

Requirements: API

The API for APM v3 is explicitly a private API. However, it would be +

Requirements: API

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.

Requirements: Security

+returned by the system API.

Requirements: Security

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.

Requirements: The User Interface

The user interface is a set of HTML pages that are used to drive the +the PGP signature and MD5 stamps information before a package install.

Requirements: The User Interface

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.

Requirements: The Developer's Interface

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.

Requirements: The Developer's Interface

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.

  • Requirements: The Site-Wide Administrator's Interface

    The requirement of the administrator's interface is to enable the +registered dependency on the sub-package.

    Requirements: The Site-Wide Administrator's Interface

    The requirement of the administrator's interface is to enable the administrator to install, enable, upgrade, disable, deinstall, and delete packages.

    Requirements: The Sub-Site Administrator's Interface

    +

    Requirements: The Sub-Site Administrator's Interface

    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.

    Implementation notes

    Despite the fact that requirements are meant to be design/implementation +

    Implementation notes

    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.

    Revision History

    Document Revision #Action Taken, NotesWhen?By Whom?
    0.1Creation8/10/2000Bryan Quinn, Todd Nightingale
    Reviewed8/11/2000John Prevost, Mark Thomas, and Pete Su
    0.2Revised and updated8/12/2000Bryan Quinn
    0.3Reviewed, revised, and updated - conforms to requirements template.8/18/2000Kai Wu
    0.4Minor edits before ACS 4 Beta.9/30/2000Kai Wu
    View comments on this page at openacs.org
    +these features should be quite straightforward.

    Revision History

    Document Revision #Action Taken, NotesWhen?By Whom?
    0.1Creation8/10/2000Bryan Quinn, Todd Nightingale
    Reviewed8/11/2000John Prevost, Mark Thomas, and Pete Su
    0.2Revised and updated8/12/2000Bryan Quinn
    0.3Reviewed, revised, and updated - conforms to requirements template.8/18/2000Kai Wu
    0.4Minor edits before ACS 4 Beta.9/30/2000Kai Wu
    View comments on this page at openacs.org