# 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.1.1.1 $