/ 
OpenInteract-1.99_04
River stage zero No dependents
/ OpenInteract2::Manual::QuickStart

NAME

OpenInteract2::Manual::QuickStart - Create an OpenInteract2 website in ten minutes!

SYNOPSIS

This part of the manual will walk you through setting up an OpenInteract2 website.

APPLICATION SERVER IN TEN MINUTES

Prerequisites

To make this quickstart install happen you'll need the following.

  • OpenInteract2 installed. This is the normal four-step installation process (see "MODULE INSTALL"); in addition to installing the various modules it will copy the script oi2_manage to somewhere in your path.

  • Access to the OpenInteract2 source directory. This includes the packages and template files necessary to create a website.

  • DBD::SQLite installed. This is a standalone, file-based SQL database you have to do very little configuration for. (Win32 users can grab the PPM from the theoryx5 repository -- see "SEE ALSO".)

Note that you do not need an install of Apache or other third-party webserver for this quick start. We use a standalone webserver using HTTP::Daemon.

Creating a Website

Set the environment variable OPENINTERACT2 to the directory where your website will live. The directory shouldn't exist yet.

$ export OPENINTERACT2=/PATH/TO/WEBSITE

(You'll need to use the full path for now, relative paths will fail in non-obvious ways.)

Many OI2 scripts use this environment variable and it saves us typing. We'll refer to this as /PATH/TO/WEBSITE throughout this guide.

Next, issue the command to create the website:

$ oi2_manage create_website --source_dir=/path/to/OpenInteract2-source

(You'll need to use the full path for now, relative paths will fail in non-obvious ways.)

The --source_dir must have at least the sample/ and pkg/ directories from the OpenInteract2 distribution.

Configuring Your Site: server.ini

Once you've done that, you'll need to edit the server configuration file. There are lots of items to edit, but for now we'll assume you want to see something running as soon as possible to see how things work.

Open up /PATH/TO/WEBSITE/conf/server.ini in your favorite text editor and make the following changes, replacing your actual website directory for /PATH/TO/WEBSITE throughout:

Set email information

Change:

[mail]
smtp_host     = 127.0.0.1
admin_email   = admin@mycompany.com
content_email = content@mycompany.com

to something relevant to your situation.

Set database metadata

Change:

[datasource main]
type          = DBI
spops         = 
driver_name   =
dsn           =
username      =
password      =
db_owner      =
sql_install   =
long_read_len = 65536
long_trunc_ok = 0

to:

[datasource main]
type          = DBI
spops         = SPOPS::DBI::SQLite
driver_name   = SQLite
dsn           = dbname=/PATH/TO/WEBSITE/oi2test.db
username      =
password      =
db_owner      =
sql_install   =
long_read_len = 65536
long_trunc_ok = 0

Set session handler

Create the directories where the session data will live:

$ cd /PATH/TO/WEBSITE
$ mkdir cache/session
$ mkdir cache/session_lock
$ chmod 777 session session_lock

And modify the server configuration to use them by changing:

[session_info]
class       = OpenInteract2::SessionManager::DBI
impl_class  = Apache::Session::MySQL
datasource  = main
expiration  = +3M
expires_in  = 0
cache_user  = 30
cache_group = 30
cache_theme = 30
  
[session_info params]

to:

[session_info]
class       = OpenInteract2::SessionManager::File
impl_class  = Apache::Session::File
datasource  = main
expiration  = +3M
expires_in  = 0
cache_user  = 30
cache_group = 30
cache_theme = 30
 
[session_info params]
Directory     = /PATH/TO/WEBSITE/cache/session
LockDirectory = /PATH/TO/WEBSITE/cache/session_lock

That's it!

Seed the Database

You need to create the database tables and seed it with initial data:

$ oi2_manage install_sql --package=SYSTEM

This tells the OI2 website you've specified in the environment variable OPENINTERACT2 to run the SQL installation routines for all packages named in the SYSTEM key. This happens to be all the packages installed when you created the website. Handy!

This should issue a bunch of messages listing the different tables created, data files used, etc. Peruse them at your leisure.

Create the Superuser Password

Now it's time to create the superuser password:

$ oi2_manage create_password --password=cindilauper

(replacing 'cindilauper' with your favorite password)

Start the Server

Now, we'll startup the standalone (LWP-based) webserver. Issue the command:

$ oi2_daemon

This uses the OPENINTERACT2 environment variable set earlier. You should see a message similar to this:

Using OPENINTERACT2 environment for website directory:
  /PATH/TO/WEBSITE
Using daemon configuration from website directory
OpenInteract2 now running at URL <http://localhost:8080>

Now fire up your web browser to the given URL and you should see the 'Welcome to OpenInteract 2!' page. Try and login as 'superuser' with the password you set. Have fun!

Behind the Curtain

If you want to see what's going on behind the scenes you can modify the debugging level. In the file /PATH/TO/WEBSITE/conf/log4perl.conf change:

log4perl.logger.OI2             = INFO

to:

log4perl.logger.OI2             = DEBUG

Restart your server once you've made the change and monitor the file /PATH/TO/WEBSITE/logs/oi2.log for what's going on behind the curtain. You may see a message like this:

2003/06/26 10:30:15: OpenInteract2::DatasourceManager 121 Disconnecting
datasource main from manager shutdown

Don't worry about it. We have to do this to prevent the forked children from sharing the parent's database handle.

Also, note that the standalone daemon pipes STDOUT to a file daemon.log found in the directory from which you started the daemon. Normally the only messages you find here are from libraries used by OI2.

You'll also find in /PATH/TO/WEBSITE/conf a file oi2.pid holding the daemon's process ID. On unix-y systems you can use this to kill the process:

$ kill -15 `cat /PATH/TO/WEBSITE/conf/oi2.pid`

MODULE INSTALL

The normal Perl module installation process is:

perl Makefile.PL
make
make test (**optional)
make install

OpenInteract2 also supports the new Module::Build process which is more portable since it doesn't need a make implementation:

perl Build.PL
perl Build
perl Build test
perl Build install

SEE ALSO

Win32 PPD for SQLite (ActivePerl 5.8x)

http://theoryx5.uwinnipeg.ca/ppms/DBD-SQLite.ppd

COPYRIGHT

Copyright (c) 2002-2004 Chris Winters. All rights reserved.

AUTHORS

Chris Winters <chris@cwinters.com>