Installation

Requirements

OASIS requires a number of external packages:

Setup

Configure your Web server for PHP (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):

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>

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.

Make sure that you have a php.ini file (usually in /usr/local/lib -- if you don't have one, you can copy the php.ini-dist from the PHP distribution into /usr/local/lib/php.ini) and that it contains the following directives:

register_argc_argv = On
track_errors = On
The first is mandatory (if you don't have this set, the maintenance scripts won't run properly). The second is optional; if you don't have it set, you won't get very helpful error messages.

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

  1. 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.

  2. Run install.php as a privileged user. This user must have the appropriate privileges to create your log directory and your script directories, chown them to the Web user and also to use "su" to run hourly_maint.php as the Web user. It's probably best to run this 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.
  3. 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.

    It is normal for hourly_maint.php to report some warnings the first time it is run (the warnings should look like: "Variable passed to each() is not an array"). It expects to see some campaigns and assignments of those campaigns to sections. Obviously, the first time you run it, there will be no campaigns or assignments.

    But 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!

  4. 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.
  5. Create a top-level section for your ad server (for example, just call it "Main").
  6. 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.
  7. On the Admin page, reload the delivery engine.
  8. 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.

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/oasis/mgmt/hourly_maint.php > /dev/null
5,10,15,20,25,30,35,40,45,50,55 * * * * /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 - nobody -c '/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!

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.