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 request/response interfaces to LWP

Change:

  [context_info]
  request               = cgi
  response              = cgi

to:

  [context_info]
  request               = lwp
  response              = lwp

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-2003 Chris Winters. All rights reserved.

AUTHORS

Chris Winters <chris@cwinters.com>

Generated from the OpenInteract 1.99_03 source.