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 -%]
[% 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 $