Installation

Requirements

OASIS runs under Linux and FreeBSD. It is known to work with RedHat 6.2 through 8.0.

OASIS requires a number of packages; if you use RedHat Linux, you can install everything from RPMs, and you won't have to compile anything.

Setup

PHP Configuration
First, make a symbolic link at /usr/local/bin/php to your standalone PHP interpreter. The OASIS installation and maintenance scripts depend on this location for the php binary.

Make sure that you have a php.ini file and that it contains the following directives:

register_globals = On
register_argc_argv = On
track_errors = On
The first two are mandatory. The second is optional; if you don't have it set, you won't get very helpful error messages.

Special note about register_globals: some administrators are uncomfortable with having register_globals on. You can use register_globals and not compromise your entire site by just enabling it for your OASIS directory. The following lines of httpd.conf can serve as an example:

<Directory /var/www/html/oasis>
php_flag register_globals on
</Directory>

OASIS Configuration/Installation
Once you have PHP and all the other software above installed, untar the OASIS distribution in a temporary location.

Edit the file oasis.cfg to set up some initial variables. This file is well-commented, so you should be able to figure out from the comments how to configure it.

Alternately, you may use contrib/makeconfig.php to generate your config file. This steps you through the questions one by one and builds oasis.cfg. Run install.php as root. When prompted for a MySQL username and password, give a name and password of a user privileged enough to add a new user to the MySQL privileges tables, create the OASIS database, and reload the mysqld. If you notice any errors in the last couple steps (where mysqladmin is called to reload, and hourly_maint.php is called with su), you'll have to manually run those commands. MySQL must be reloaded in order to allow the OASIS scripts to connect to the database. hourly_maint.php must be run to load up shared memory for OASIS.

If you see warnings about shared memory or database connections, then you are going to have to run hourly_maint.php by hand. If you have to run hourly_maint.php by hand, run it like this:

hourly_maint.php start

and be sure to run it as the Web user!

Apache Configuration
Configure your Web server for PHP and include the oasis_httpd.conf file that was created during the installation process (and if you're dedicating this server to OASIS, you might want to set up your DocumentRoot to point to the OASIS directory for shorter URLs). Here's how I do it for Apache (these lines go in /usr/local/apache/conf/httpd.conf):

Include conf/oasis_httpd.conf

DocumentRoot "/path/to/oasis"
AddType application/x-httpd-php .php
php_admin_flag track_errors on

<Directory "/path/to/oasis">
    Options None
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>

<IfModule mod_dir.c>
  DirectoryIndex index.html index.php
</IfModule>

<Files *.inc>
  Order deny,allow
  Deny from all
</Files>

<Files *_maint.php>
    Order deny,allow
    Deny from all
</Files>

<Files check_inventory.php>
    Order deny,allow
    Deny from all
</Files>

Note that the path to oasis_httpd.conf is relative to the Apache ServerRoot.

It's important to deny access to your .inc files; they contain very sensitive information, and without a configuration entry specifically denying access to those files, intruders could pull up those files and use the information to compromise your system.

It's also critical to deny access to your maintenance scripts.

Restart Apache.

OASIS Tests
Now you should be able to go into your OASIS interface, which is found at "http://[oasis_host][oasis_url]mgmt/" (for example, if oasis_host = oasis.yourdomain.com and oasis_url = /oasis/, you'll go to http://oasis.yourdomain.com/oasis/mgmt/ to open the management interface). Log in with the username and password you specified in oasis.cfg.

Create a top-level section for your ad server (for example, just call it "Main").

Create an advertiser and a campaign (probably easiest to use the Campaign Insertion interface under "New Campaign"). Go into the Campaign interface to make sure the campaign is set to "Active". Also, make sure that it is assigned to the top-level section you created, and make sure that its dates cover the current day.

On the Admin page, reload the delivery engine.

Now go to the Section interface, get the sample URL for your top-level section (just click on the section's name), and then open the URL for the IMG SRC. You should see your first banner served up.

If you don't see a banner, make sure that you see something assigned to the section under Hourly Assignments (under Delivery Engine Internals on the Admin page). Also make sure that the width and height specified in the URL match those for the ad(s) you put into your first campaign. If you don't see any assignments for Section 1, then most likely your campaign is not Active, it wasn't assigned to Section 1, or its dates do not cover the current day.

System Configuration
Once you're getting banners, you need to set up cron jobs (hourly_maint.php and minutely_maint.php) in the crontab of the user as which your Web server runs:

0 * * * * /path/to/php /path/to/oasis/mgmt/hourly_maint.php > /dev/null
5,10,15,20,25,30,35,40,45,50,55 * * * * /path/to/php /path/to/oasis/mgmt/minutely_maint.php > /dev/null

If you aren't already rotating the logs of your Web server, make sure that you set up some sort of log rotation. Here's how I rotate Apache logs with logrotate (these lines go in /etc/logrotate.conf):

/usr/local/apache/logs/error_log {
    daily
    nocreate
    rotate 14
}

/usr/local/apache/logs/access_log {
    daily
    nocreate
    compress
    postrotate
        /usr/local/apache/bin/apachectl restart
    endscript
    rotate 14
}

Set up OASIS to start upon a system boot. Add these lines to /etc/rc.d/rc.local:

su - apache -c '/path/to/php /home/webdocs/oasis/mgmt/hourly_maint.php start'
/usr/local/apache/bin/apachectl start

Of course you need to substitute your own paths and username in these lines!

Finally, make sure that MySQL and Apache are starting at system boot. Under Linux, you can use chkconfig to control what starts up at the various runlevels.

What the install script does

Just so you have a better understanding of what install.php does, here's a general breakdown of its responsibilities.