Documentation for oi_manage


NAME
    oi_manage - Manage OpenInteract websites and packages

SYNOPSIS
    oi_manage [options] [command]

    Administration commands:

       install, install_package

    Package development commands:

       create_skeleton, export_package, check_package

    Website creator commands:

       create_website, apply_package, upgrade_package, 
       remove_package, install_sql, install_template, 
       dump_template, remove_template, test_db

    Other commands:

       initial_packages, list_packages, list_actions

    For more information, run 'oi_manage --man'

COMMON COMMANDS
    Commands by the Administrator:

     install            - Install OpenInteract
     install_package    - Install package to the base

    Commands by the Package Developer:

     create_skeleton    - Create a skeleton package for development
     export_package     - Export package(s) to distribution file(s)
     check_package      - Ensure that package passes initial inspection

    Commands by the Website Creator:

     create_website     - Create a new website
     apply_package      - Install a package from base to website
     upgrade_package    - Upgrade a website package
     remove_package     - Remove a package from a website
     install_sql        - Install the SQL for packages
     install_template   - Install package templates to the database
     dump_template      - Dump package templates to the filesystem
     remove_template    - Remove package templates from the database
     test_db            - Test database settings in 'server.perl'

    Other commands:

     initial_packages   - List packages marked as 'initial'
     list_packages      - List packages installed to app or base
     list_actions       - List actions currently implemented in website

COMMON OPTIONS
    Summary of common options:

     --base_dir           OpenInteract install directory
     --website_dir        Website install directory
     --website_name       Website name
     --package_dir        Directory with package subdirectories (usually devel)
     --package_file       Distribution file containing an OpenInteract package
     --package            List packages to operate on
     --package_list_file  File specifying packages to operate on
     --dump_dir           Directory to dump stuff into
     --help               Display brief help
     --man                Display full help

    Details:

     --base_dir=/path/to/OpenInteract

        Name the directory where OpenInteract is installed. You can set
        the environment variable 'OPENINTERACT' instead of passing the
        value on the command-line, We recommend you set this environment
        variable for all OpenInteract users and developers.

     --website_dir=/path/to/OpenInteract/website

        Name the directory where an OpenInteract website is
        installed. This directory will have the website package database
        in the 'conf/' directory. You can set the environment variable
        'OIWEBSITE' instead of passing the value on the command
        line. However, setting this permanently will cause you problems,
        so it is best to set on a temporary basis.

     --website_name=MyAppName

        Name of your website. Must be all one word (no underscores or
        anything), and StudlyCaps are A-OK (in fact, recommended). Note
        that this name becomes your perl namespace, so all your packages
        become 'MyAppName::News' and 'MyAppName::WebLink::Handler', etc.

     --package_dir=/path/to/my/devel/packages

        Name the directory where you do your OpenInteract
        development. This is used by the 'export_package' and the
        'check_package' commands. This directory can also be where a
        single package is -- we also look at the 'package' parameter to
        discern which way to use 'package_dir'.

     --package_file=an-oi-package-x.xx.tar.gz

        OpenInteract packages are distributed in common tarballs, which
        can be created by the 'export_package' command and installed by
        the 'install_package' command.

     --package=a,b,c,d  OR --package=a --package=b --package=d

     --package_list_file=/path/to/package_list

        File containing package names, one per line, without version
        numbers or anything else. Blank lines and lines beginning with a
        '#' are skipped. You can substitute this wherever you see
        '--package' specified as a parameter in the discussions below.

     --dump_dir=/path/to/dump/stuff

        Specify a directory where you would like to dump something -- such
        as the SQL for a package or the templates belonging to a
        package. Dumping routines typically have a designated place for
        this (usually the 'dump/' directory in the area pertaining to what
        is being dumped), but sometimes you might want to put the data
        elsewhere.

    Other options depend on the *command* you choose and are listed
    under that command below.

DESCRIPTION
    oi_manage is the command-line interface for managing packages
    within OpenInteract and installing new OpenInteract websites. It
    is also useful for developers so they can export their work into
    a *tar.gz* file for distribution, or install it into the
    OpenInteract package database.

COMMANDS
    The following tools and actions are available from oi_manage:

  INSTALL

    Command: install

    Install OpenInteract. Note that you must be in the OpenInteract
    source directory to run this command. For instance, a typical
    installation might look like the following sequence:

     >> tar -zxvf OpenInteract-1.01.tar.gz
     >> cd OpenInteract-1.01
     >> perl Makefile.PL
     >> make
     >> make test
     >> make install
     (file 'oi_manage' is now in /usr/local/bin)
     >> /usr/local/bin/oi_manage --base_dir=/opt/OpenInteract install

    You should only ever need to do this once. But just in case, it
    might be a good idea to keep the initial source directory
    around.

  INITIAL PACKAGES

    Command: initial_packages

    Just lists the initial package oi_manage is currently configured
    to install when given a 'create_website' command.

  LIST PACKAGES

    Command: list_packages

    Required options -- one of the following:

     --base_dir=/path/to/OpenInteract
     --website_dir=/path/to/my_website

    List the packages currently installed in a website or in the
    base OI installation.

  LIST ACTIONS

    Command: list_actions

    Required options:

     --website_dir=/path/to/my_website

    Bootstrap an OpenInteract environment from the command line and
    inspect it to see what actions are created in the action table.

    Output includes the action name, the package the action is found
    in, and either the class and method used to call it or the
    template which implements it.

    This can be extremely useful if you are unsure what actions your
    website currently implements, and for ensuring that you do not
    chose an action for your new package that is already in use
    elsewhere.

  CREATE SKELETON

    Command: create_skeleton

    Required options:

     --package=mypackagename
     --base_dir=/path/to/OpenInteract

    Creates skeleton package(s) in your current directory for
    development.

    This includes:

    *   The necessary directories

    *   An initial `package.conf' file

    *   A documentation template and index

    *   Commented sample `conf/spops.perl' and `conf/action.perl',
        configuration files

    *   Commented sample `OpenInteract/SQLInstall' file

    *   Commented sample template files in `template/dummy.meta', and
        `template/dummy.tmpl'

    *   A starter changelog (Changes) and

    *   A working MANIFEST file along with MANIFEST.SKIP with common
        patterns for files not to include in the MANIFEST.

    If you specify multiple packages, multiple directories will be
    created in your current directory.

  EXPORT PACKAGE

    Command: export_package

    You can run this one of two ways:

    1. Export a single package by changing to its directory and
    running this command without any parameters.
    2. Specify the following parameters for multiple packages:
         --package_dir=/path/to/my/packages
         --package=x (at least one)

        All packages you specify that the command can find in the
        'package_dir' directory will get distributions created.

    This is a utility for people developing new packages for
    OpenInteract. Some might consider it a Bad Idea to develop
    packages under the base OpenInteract/pkg directory -- for new
    uninstalled packages it is not a problem, but once you start
    doing that you start working on packages in-place, and before
    you know it everything it out of whack. Best not go there.

    So what this utility does is peek into a directory for a
    'package.conf' file. This is a simple file with information
    about your package in a simple format. Here is an example:

     name           MyKillerApp
     version        1.14
     dependency     YourKillerApp 1.20
     dependency     TheirLameApp  0.89
     author         Zippy Doodad (zippy@doodad.com)
     author         Bolt (bolt@uno.com)
     url            http://mykillerapp.com/
     sql_installer  OpenInteract::SQLInstall::MyKillerApp
     description
     This package implements what everybody -- especially the town of
     Ottumwa, Iowa -- thinks is a KillerApp. You will too.

    So we read in configuration and ensure you have the required
    fields. (Currently, the fields 'name', 'version' and 'author'
    are required, although no validation is performed on them.)

    If the configuration file passes muster, we then check out the
    MANIFEST that accompanies your package. MANIFEST lists the files
    that should be distributed with your package.

    If 'export_package' finds any files in MANIFEST not in the
    directory or if it finds files in the directory not specified in
    MANIFEST, it will give you a warning but still create the
    distribution. You then have the option of distributing your
    package as-is (probably a bad idea, but you might have your
    reasons) or fixing the problem and re-creating the distribution.
    You can go through this process as many times as necessary since
    the 'export_package' command does not change any information in
    your package.

    You may also specify a MANIFEST.SKIP file that determines which
    files should not be compared to the MANIFEST to ensure that you
    do not have any extra files floating around. Each line in the
    MANIFEST.SKIP file is a regular expression matching files that
    should not be included in MANIFEST. For example, if you specify
    in MANIFEST.SKIP:

     \bCVS\b

    Then when this command finds files matching this pattern (all
    your CVS directories) in your package directory, it will not
    complain and tell you there are extra files in the directory.

    (Since we use the ExtUtils::Manifest manpage to manipulate the
    MANIFEST file, including the MANIFEST.SKIP file, you might find
    it helpful to read more about it.)

    The command 'create_skeleton' creates a default MANIFEST and
    MANIFEST.SKIP for you, although it is your responsibility to add
    your files to MANIFEST and your exclusion patterns to
    MANIFEST.SKIP after that.

    Once we get this file and directory listing, we use them to
    create a distribution file -- just a '.tar.gz' file conforming
    to certain standards -- suitable for installation in another
    OpenInteract installation with the 'install_package' command.

  CHECK PACKAGE

    Command: check_package

    Required options:

    One of the following:

    1.  None (check the package in the current directory)

    2.  Check the package in a particular directory:

         --package_dir=/path/to/my/devel/package

    3.  Check one or more packages in a particular website:

         --website_dir=/path/to/my_website
         --package=x (at least one)

    4.  Check one or more packages in the installation directory.

         --base_dir=/path/to/OpenInteract
         --package=x (at least one)

    This command checks that a package has the bare necessities and
    that the files at least pass some basic sanity checks.

    Files we check:

     Changes
     package.conf
     conf/*.perl
     *.pm
     /*.pm (if this is a website)

    We also ensure that the files found in MANIFEST are all there
    give you a warning if there are extra files in the directory not
    found in MANIFEST.

    It is probably a good idea to always run this before you send a
    package to someone else. (Commands like this usually spring from
    the embarrassment of someone else, so learn the lesson :)

    This leads to the common idiom of:

     > ... work on package ...

     > cd /my/package/devel/dir

     > oi_manage check_package
     (all is ok)

     > oi_manage export_package

     > scp mypkg-1.21.tar.gz me@mywebste:/home/httpd/pkg

     > ...

  INSTALL PACKAGE

    Command: install_package

    Required options:

     --base_dir=/path/to/OpenInteract
     --package_file=/path/to/package-x.xx.tar.gz

    Installs a package from a distribution file, which are just
    tar.gz files with the package information in them. The steps to
    install the package include:

    *   Unpack the distribution and determine the package name and
        version

    *   See if that package and version are already installed

    *   Copy the files to the base OpenInteract directory

    *   Install the package information to the OpenInteract package
        database

  CREATE WEBSITE

    Command: create_website

    Required options:

     --website_name=MyAppName
     --website_dir=/path/to/my_website
     --base_dir=/path/to/OpenInteract

    Creates a new directory for your website and all the necessary
    subdirectories, so ensure that 'website_dir' does not exist yet.

    This command also copies over configuration files and replaces
    various keys with ones specific to your website. The program
    creates a simple stash class for you as well as installs the
    base packages necessary for OpenInteract to function.

    After running this command, you typically have to only edit some
    configuration files and your website can be up and running! See
    the file `INSTALL.website' distributed with O0penInteract for
    more information.

  TEST DB

    Command: test_db

    Required options:

     --website_dir=/path/to/my_website

    Just tests out whether you can establish a connection to the
    database for which you have specified parameters in the
    `conf/server.perl' configuration file in your website.

    ***NOTE***

    Just because your database connection works from the command
    line does NOT mean that it will automatically work from your web
    server. Hopefully, your web server runs under a user with
    minimal permissions, which can affect shared library and other
    types of access. In addition, your command-line environment
    might be set up properly to connect to your database while the
    web server environment is not. More is in the entry: *When I run
    a perl script from the command line, it works, but, when I run
    it under the httpd, it fails! Why?* in `perldoc DBI::FAQ'.

    In the future it will also try to create a table, put data into
    the table, get information from the table, remove information
    from the table and remove it as well. (But this is also a
    relatively low priority, so if you are feeling industrious then
    have a go at it!)

  APPLY PACKAGE

    Command: apply_package

    Required options:

     --website_dir=/path/to/my_website
     --package=x (at least one)

    Applies a package from the installed base of packages in
    OpenInteract to your website. (The package must have first been
    installed with 'install_package', although future versions of
    OpenInteract may allow you to install a package to a website
    only.) This includes localizing all the files (changing the
    namespace from 'OpenInteract::' to 'MyApp::') and copying all
    the templates, SQL structures and default data/security to your
    website directory.

    APPLYING THE PACKAGE DOES **NOT** INSTALL THE SQL FOR YOU. SEE
    the section on "INSTALL SQL".

    This option will by default apply the latest version of the
    available package for you. Applying earlier versions is not yet
    supported.

  REMOVE PACKAGE

    Command: remove_package

    Required options:

     --website_dir=/path/to/my_website
     --package=x (at least one)

    Removes the package from the website. Note that we do not
    currently support removing the files associated with the
    package, or the templates in the database that belong to the
    package. If you want to truly eradicate your package, you should
    do the following:

     >> oi_manage --pacakage=mypackage \
                  --website_dir=/path/to/my_website \
                  remove_template
     >> oi_manage --pacakage=mypackage \ 
                  --website_dir=/path/to/my_website \
                  remove_package
     >> cd /path/to/my_website/pkg
     >> rm -rf mypackage-x.xx 

  UPGRADE PACKAGE

    Command: upgrade_package

    Required options:

     --website_dir=/path/to/my_website
     --package=x (at least one)

    Upgrades a package from the base installation to a website. For
    instance, if your website has the package 'classified-1.04' and
    the base installation has the package 'classified-1.11', then
    you can simply do:

     >> oi_manage --website_dir=/path/to/my_website --package=classified \
                  upgrade_package 

    Note that the files from the older version of your package are
    kept intact, but they are no longer used. This program does not
    currently support the more complicated task of trying to find
    the differences between your files and the new files -- you are
    left to your own devices.

SQL COMMANDS
    One of the difficulties in any website framework is getting data
    into the framework from somewhere else and getting data out of
    the framework to somewhere else.

    OpenInteract provides a flexible framework for the first and the
    seedlings of something for the second. Exporting data into the
    format used by OpenInteract is on the list of things to do and
    has a relatively high priority, although your help could push it
    over the top!

  INSTALL SQL

    Command: install_sql

    Required options:

     --package=x (at least one)
     --website_dir=/path/to/my_website

    This command goes through a list of packages and installs the
    initial tables and data for each one. It is also empowered to
    run perl scripts that set initial security or do other tasks.

    Generally, this works by each package creating an *Installer
    Class* that is used by the OpenInteract::SQLInstall manpage. The
    dispatching class provides a number of tools for the
    implementing class so that each package does not need to do
    terribly much. However, if the package needs to do quite a bit
    of customization, it can.

    Please see the the OpenInteract::SQLInstall manpage module for
    more information on how this whole process works.

  DUMP SQL

    Command: dump_sql

    Required options:

     --package=x (at least one)
     --website_dir=/path/to/my_website

    Useful option:

     --dump_dir=/path/to/dump/sql

    Dumps data from the tables and security used by the website into
    a number of files. If 'dump_dir' is specified the files will go
    there; if not, they will go into the 'data/dump/' directory
    under the package specified in the 'website_dir'.

    This is still under development. How this will work:

    *   You define parameters in the SQLInstall class for your package
        that determines how you want to dump certain data.

    *   After running the command in this script, you will have a set of
        files in the `dump/' subdirectory of one or both of the
        `data/' and `struct/' package subdirectories. (Or in the
        'dump_dir' that you choose) These files can be distributed
        with the package and used to install data on other
        OpenInteract installations.

TEMPLATE COMMANDS
    This script should help with the whole template editing process.
    Editing templates via the browser interface can be tedious. HTML
    interfaces are, shall we say, not very robust for dealing with
    most data. (Now, if we can only get XEmacs embedded as a Mozilla
    widget for the TEXTAREA item...)

    Anyway, most people will naturally prefer editing templates in
    their favorite editor -- say, XEmacs -- and we would like to
    encourage such productive behavior. We support this in two ways:

    Calling Templates

    This is covered elsewhere, but worth mentioning here. When you
    call a template with a last parameter like the following:

     { db => 'my_template_name', package => 'my_pkg' }

    The system first looks in the database for a template with the
    given name. If it is not found, it then looks to the filesystem
    in the specified package. If it is not found there, the system
    raises an error which is displayed onscreen.

    What this means is that you can start creating your templates
    using files -- test them, go through umpteen iterations of
    input-view-debug until everything is stable, then add the
    template to the database for performance reasons. You can still
    update the template from there, but the editing cycle once the
    template is in the database is stretched out. (At least for now
    it is.)

    There are two commands to let you transfer templates between the
    filesystem and the database, and one to remove them from the
    database altogether.

  INSTALL TEMPLATE

    Command: install_template

    Required options:

     --package=x (at least one)
     --website_dir=/path/to/my_website

    Each package has its own directory for templates, and you can
    choose to transfer these files into the database at any time.
    You can even do so once the templates are already in the
    database -- the system will first check to see if a template
    exists and update its information before creating an entirely
    new one.

    Note that all templates require a 'tmpl' file and a 'meta' file.
    A typical 'tmpl' file might be:

     Typical Template File
     ==============================
     [% IF user %]

     [%- label = 'User Info'  IF not label -%]

     
[% label %]
[% user.first_name %] [% user.last_name %] ([% user.login_name %])
Edit my info | Logout
[% END %] ============================== And its accompanying 'meta' file might be: Typical Meta File ============================== name: user_info_box title: Box that shows login user information package: base_component Parameters for this component: --user: the user object (returns nothing if it does not exist) --return_url: URL of the current page, which we will come back to if the user logs out --label: What is the label for the box? (default: 'User Info') ============================== We use the information in the 'meta' file to name or location template object when we install the templates. DUMP TEMPLATE Command: dump_template Required options: --package=x (at least one) --website_dir=/path/to/my_website Useful option: --dump_dir=/path/to/dump/stuff Dumps the templates for a package from the database to the filesystem. If you do not specify a 'dump_dir', all dumped templates are stored in the directory within a package 'template/dump/' rather than just 'template/'. (What you do with the templates after that is your business.) REMOVE TEMPLATE Command: remove_template Required options: --package=x (at least one) --website_dir=/path/to/my_website Removes all templates in the specified package(s) from the database used by 'website_dir'. OTHER METHODS If you are adding functionality to this script, these methods can be useful. initialize_db_actions( $website_dir, $action ) This method initializes OpenInteract without mod_perl, reading in the configuration, creating an the OpenInteract::Request manpage object and connecting the database specified in the configuration. Note that this creates the whole environment -- SPOPS classes are created and everything. Return value is an the OpenInteract::Request manpage object ($R). open_base_config_file Just a wrapper around the `read_base_config' method in the OpenInteract::Package manpage -- we provide a common error message. print_status_line Display information from a 'status' record. Each status record is a hashref which can have the following keys: ok True if status is ok, undef/0 otherwise name Name of the package version Version of the package msg Message to accompany status (gets displayed whether status is 'ok' or not) EXAMPLES Some quick examples: Installing OpenInteract for the first time, to the directory '/opt/OpenInteract': >> tar -zxvf OpenInteract-1.01.tar.gz >> cd OpenInteract-1.01 >> perl Makefile.PL >> make >> make test >> make install >> /usr/local/bin/oi_manage --base_dir=/opt/OpenInteract install Create a new website: >> /usr/local/bin/oi_manage --website_dir=~/OIApp \ --website_name=MyOIApp \ --base_dir=/opt/OpenInteract create_website Install a package to the OpenInteract installation directory with a file you have downloaded: >> /usr/local/bin/oi_manage --base_dir=/opt_OpenInteract \ --package_file=/tmp/downloadedpackage-1.41.tar.gz \ install_package Then apply the new package to your website: >> /usr/local/bin/oi_manage --website_dir=~/OIApp \ --package=downloadedpackage apply_package Create a new skeleton directory for a package you will develop: >> cd ~/OpenInteract >> /usr/local/bin/oi_manage --package=mydevelpackage \ create_skeleton After you have worked on your new package, you want to create a distribution file. First, run a check on the package: >> /usr/local/bin/oi_manage \ --package_dir=~/OpenInteract/mydevelpackage \ check_package If everything looks ok, then export it to a .tar.gz >> cd ~/OpenInteract/mydevelpackage >> /usr/local/bin/oi_manage export_package Install it to the main OpenInteract installation: >> /usr/local/bin/oi_manage --base_dir=/opt_OpenInteract \ --package_file=~/OpenInteract/mydevelpackage/mydevelpackage-0.01.tar.gz \ install_package And then apply it to your website: >> /usr/local/bin/oi_manage --website_dir=~/OIApp \ --package=mydevelpackage apply_package List the website packages to make sure it is there: >> /usr/local/bin/oi_manage --website_dir=~/OIApp list_packages You might want to bring its templates into the website database: >> /usr/local/bin/oi_manage --website_dir=~/OIApp \ --package=mydevelpackage install_template And then create the SQL structures: >> /usr/local/bin/oi_manage --website_dir=~/OIApp \ --package=mydevelpackage install_sql TO DO Progress Indicator When you are doing actions on multiple packages -- installing OpenInteract, creating a website, etc. -- you do not get feedback as the action is happening but rather everything at the end. 'Upgrade' analog to 'Install' After you have installed OpenInteract using the 'install' command, you do not want to install it again. You just want to do: perl Makefile.PL make make test make install oi_manage upgrade And have all the packages in 'pkg/' be installed anew. Should not be too hard. Friendly Dependency Finder At install_package time, inspect the modules used by the package -- list_module.dat, ISA, etc. If we find one that is not installed, ask the user if he/she would like to install it and use CPAN to do so. File Verification Integrate MD5 checksum verification into the system for each file as well as for the package distribution on the whole. SQL: Create an Equivalent Dumper It would be nice to have a database-independent data dumping program that put the data into the format used by `OpenInteract::SQLInstall'. This actually should not be too hard, since the format is pretty simple. We might need to add information to the object (in `spops.perl') so that it can tell which fields are 'class' fields or other fields that need to be transformed. BUGS SEE ALSO the OpenInteract::Package manpage, the OpenInteract::SQLInstall manpage, the OpenInteract::Startup manpage COPYRIGHT Copyright (c) 2001 intes.net, inc.. All rights reserved. This script is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHORS Chris Winters Christian Lemburg suffered through early versions of this installer and package management system and offered insightful feedback. Nate Haas and Marcus Baker also worked with early versions of this installer and provided many helpful usability, documentation and functionality comments. REVISION Revision: $Revision: 1.3 $