Installing SteelBlue

System Requirements

SteelBlue can be used on the command-line without a Web server (which is be useful for creating volumes of static pages), but it was primarily designed to act as an application server.

SteelBlue makes use of the ANSI C++ Standard Template Libraries (STL). Therefore, in order to compile SteelBlue, we suggest you use Visual C++ 6 (for Win32), GCC 2.8 or later, egcs 1.1.2 or later, or Sun WorkShop Compilers 5.0 or greater. For compilation you will also need the C libraries and include files for your relational database.

Download SteelBlue

Download the latest version of SteelBlue from http://www.steelblue.com/download.html. There are a series of binary (compiled) distributions for particular system configurations (i.e. Win32 and Access, Linux 2.3 and MySQL, etc.). If your configuration does not have an associated binary distribution, please download the latest source distribution.

Automatic Installation

Currently there are two binary distributions that will do a complete installation of SteelBlue including creating a database instance, installing the SteelBlue CGI executable, and creating a SteelBlue configuration file. One distribution is an InstallShield executable for Win32 designed for Apache or IIS and Access. The other distribution is a RedHat RPM designed for Apache and mySQL. If you have either of these configurations, we suggest you use the associated distributions. If you don't, please read on.

Distribution Structure

The standard distribution of SteelBlue has the following directories and files: 

BasePages/     - Default introductory SteelBlue scripts
doc/           - Documentation, including the book "Programming 
                 SteelBlue" in HTML
examples/      - Example applications
schema/        - Basic minimum schemas required by SteelBlue for 
                 various databases.
src/           - The C++ source for SteeBlue and auto-
                 documentation perl scripts.
CheckUtils.js  - The JavaScript file used for client-side type-
                 checking of forms
steelblue      - The steelblue executable (UNIX binary 
                 distribution)
steelblue.exe  - The steelblue executable (Win32 binary 
                 distribution)
steelblue.conf - A sample configuration file
INSTALL.TXT    - A text version of this file

Compiling

If you have a binary distribution that matches your configuration, you do not need to compile SteelBlue. Rejoice and skip to the section Quick Install.

Editing the Makefile or Project File

In the src/ directory there is a "Makefile" for UNIX and LINUX systems, and a "SteelBlue.dsp" Visual C++ 6 project file for Win32. In either case, definitions need to be chosen to match your system configuration. For UNIX and LINUX, the "Makefile" reads a file named "config.mk" for the system configuration definitions. A "config.mk.sample" file is provided with the distribution. Trying to run "make" without "config.mk" will cause "config.mk.sample" to be copied to "config.mk".

The following compiler flags are available: 

LINUX        - Various OS (1 must be defined)
SOLARIS
DUNIX  
WIN32  

USE_ODBC     - Various databases (at least 1
USE_MYSQL      must be defined)
USE_MSQL
USE_ORACLE
USE_ORACLE8
USE_PGSQL
USE_SYBASE

SWAPVALUE    - Define if your database doesn't accept
               a column named "val"

NO_CRYPT     - Define if you do not have access to
               crypt(3)

In the VC++ project file WIN32, USE_ODBC, and NO_CRYPT are defined by default. In the UNIX Makefile you will need to uncomment the flags appropriate to your configuration.

Making It

For UNIX execute "make". It will compile and copy the steelblue executable to the the root directory of the distribution.

For Win32 build the steelblue.exe executable. It will compile and place the executable in the src\Release\ directory.

Quick Install

In this section we describe the quickest technique to get SteelBlue up and running with public access on your system. For long-term installation or installation for multiple applications please see Proper Installation.

Create a Database

In the directory schema/ there are the minimum SteelBlue table definitions for many different databases. Also, there is an Access file with the minimum tables defined. Create an instance of your database (call it STEELBLUE for testing purposes) and create the tables found in the scripts.

Copy the SteelBlue Executable

Copy the SteelBlue executable into the cgi-bin directory of your Web server. For UNIX, make sure that the executable has execute permission by the user running the Web server.

Create the Configuration File

In the cgi-bin directory of your web server, create the file "steelblue.conf". Alternatively, the configuration file can be placed in C:/ in Win32, or /etc/ in UNIX. In the configuration file place the lines: 

base-page-dir  = STEELBLUE_DIR/BasePages/
welcome-screen = welcome.sb
sb-url        = /cgi-bin/steelblue
login-object   = PublicLogin
use-db         = ODBC  # one of ODBC MYSQL MSQL ORACLE PGSQL SYBASE
                       # depending on your DB
db-username    =       # Enter username if needed
db-password    =       # Enter password if needed

For "base-page-dir", replace STEELBLUE_DIR with the directory into which you installed the SteelBlue distribution. For "use-db", place the database you are using. For "db-username" and "db-password", place the username and password you are using for the database user (leave blank if none is needed).

Please see http://www.steelblue.com/ProgrammingSteelBlue/configuration.html for a reference on all of the configuration options.

Copy CheckUtils.js (Optional)

If you want automatic client-side JavaScript checking of input element data-types (suggested), you need to install the file "CheckUtils.js". You will find CheckUtils.js in the root directory of your SteelBlue distribution. Copy it into your htdocs/ directory of your Web server. Then add the following line to your "steelblue.conf" file: 

check-util = /CheckUtils.js

To support automatic type checking in Netscape 3, add the following line: 

check-util-file = WEB_DIR/htdocs/CheckUtils.js
Where "WEB_DIR/htdocs/CheckUtils.js" is the full path the CheckUtils.js file in your local filesystem (for example "C:/progra~1/apache~1/apache/htdocs/CheckUtils.js").

Test the Installation

Congratulations! You should now be able to go to http://localhost/cgi-bin/steelblue and access SteelBlue running on your local system. (If you are installing SteelBlue onto a remote system, replace "localhost" with the Web name of the system.)

Proper Installation

For a long-term installation of SteelBlue or installing multiple applications on a single server, we suggest that you use the instructions in this section.

Install SteelBlue Executable

SteelBlue is primarily a program given life by a web server. As such it makes the most sense to put SteelBlue somewhere under your main web server directory. For example, if Apache (a web server) is installed in WEB_DIR, then its advised that you create the SteelBlue directory WEB_DIR/SteelBlue/. However, as your applications grow in size and number it may make more sense to separate the web server from the application server.

The recommended method of directory structure is something like: 

WEB_DIR/SteelBlue
                  \
                  +- bin
                  +- html
                         \
                          +- scripts

In the bin directory will reside the SteelBlue executable, steelblue, (or steelblue.exe for Win32) and the configuration file, "steelblue.conf". SteelBlue looks in two places for the configuration file: first in the current directory, and then in C:/ for Win32 and /etc/ for UNIX.

The html directory initially contains only one directory, scripts. The scripts directory contains only one file, "CheckUtils.js".

The final installation will look like: 

WEB_DIR/SteelBlue
                  \
                   +- bin
                   |      \
                   |       +- steelblue
                   |       +- steelblue.conf
                   |
                   +- html
                           \
                            +- scripts
                                       \
                                        +- CheckUtils.js

This unfortunately will not do anything at the moment. We have to set up the supporting software.

The rational behind this structure is that a typical web application has two parts, static and dynamic pages. Static pages are serverd out of the html directory and dynamic pages from the bin directory (more or less, SteelBlue will actually grab the dynamic page from anywhere its configurated to, but to the web server, its coming from bin).

This is a SteelBlue-centric installation which is appropriate for learning SteelBlue. A second method is more Application-centric. It mimics the above installation but the top-level directory is no longer SteelBlue but the name of the application.

Configuring

SteelBlue

All of SteelBlue's runtime configuration options are specified in the file steelblue.conf which is located in either the directory where steelblue was executed or failing that, in the directory /etc/ for UNIX or C:/ for Win32.

Here is an example conf file: 

# SteelBlue configuration file

# URL of CheckUtils.js
check-util = /SteelBlue/html/scripts/CheckUtils.js
# Filesystem location
check-util-file = WEB_DIR/SteelBlue/html/scripts/CheckUtils.js

#set location of sendmail
mail-prog = /usr/sbin/sendmail

# set the time zone
# Hours from GMT (-5 is EST, -8 PST)
time-zone = -5

# DB settings
db-username     = steelblue
db-password     = susageP

# This must also be specified at compile time
use-db = MYSQL

# Default settings (can be overridden by each application)

# Database name
 DBName         = SteelBlueExamples
# Configure up database tables
 user-table     = AuthUsers
 ticket-table   = Ticket
 swap-table     = Swap


#
# Each application can have its own section.
# Sections are matched to the URL of the request sent to the web
# server and whatever follows the BEGIN line.
# So the URL http://localhost/SteelBlue/examples/steelblue
# will match the next section.

#

BEGIN = examples
# Location of the SteelBlue scripts
 base-page-dir  = WEB_DIR/SteelBlue/BasePages/
# Page to display upon successful login
 welcome-screen = welcome
# URL of application (loading this URL will load the login-screen).
 sb-url        = /SteelBlue/bin/steelblue
 DBName         = SteelBlueExamples
END

#
# End steelblue.conf
#

Database

The database has to be configured with three simple tables. The basic schema follows: 
Ticket
  username      varchar(20)
  ticket        varchar(20)
  screen        varchar(20)
  timeout       varchar(20)
  ip            varchar(20)
  institution   varchar(7)

AuthUsers
  username      varchar(20)
  institution   varchar(20)
  password      varchar(20)

Swap
  username      varchar(20)
  institution   varchar(20)
  namespace     varchar(200)
  tag           varchar(200)
  val           varchar(200)

Schemas for various databases are provided in the schema directory. For mysql on Unix one would perform the following steps: 

# create the database
mysqladmin -u root create SteelBlueExamples

# create the steelblue tables
mysql -u root SteelBlueExamples < sb/schema/mySQL.schema.sql

Web Server

The web server configuration is fairly simple. In some installation cases you won't have to reconfigure the web server at all. However, if you follow the installation of SteelBlue described above then you'll need to inform the web server of two things. First that the directory SteelBlue/bin is to contain CGI executable programs and second that SteelBlue/html is to contain HTML files accessible by the web server. Using apache one would add the following two line to httpd.conf (where WEB_DIR is the directory under which you placed the SteelBlue directory): 

Alias WEB_DIR/SteelBlue/html/ /SteelBlue/html/
ScriptAlias WEB_DIR/SteelBlue/bin/ /SteelBlue/bin/

To get the example BasePages from the standard distributions working you would add 

ScriptAlias WEB_DIR/SteelBlue/bin/ /SteelBlue/examples/
This will allow URLs like 
http://localhost/SteelBlue/examples/steelblue
to execute steelblue and read the appropriate examples section of the configuration file. Notice that with the above configuration the URLs: 

http://localhost/SteelBlue/bin/steelblue
http://localhost/SteelBlue/examples/steelblue

both execute the same copy of SteelBlue.

It is through the configuration of both SteelBlue and the web server that we create different web applications. To create a distinct SteelBlue application involves first configuring the web server to respond to a URL with a unique string (in the case above we chose "examples"). Then you will create a BEGIN = examples ... END block in steelblue.conf that tells steelblue where to find the SteelBlue scripts, the database, and other options for that application.

The web server must be restarted for these changes to take effect.

Testing

To test the installation it is neccessary to install some files for SteelBlue to process. Some example code is provided in the BasePages directory of the SteelBlue distribution (further examples are placed in the examples directory). Copy the BasePages directory to WEB_DIR/SteelBlue to create a directory structure show below. 

WEB_DIR/SteelBlue
                  \
                   +- bin
                   |      \
                   |       +- steelblue
                   |       +- steelblue.conf
                   |
                   +- html
                   |       \
                   |        +- scripts
                   |                   \
                   |                    +- CheckUtils.js
                   |
                   +- BasePages
                               \
                                +- welcome

Depending upon the web configuration you've choosen the following should work: 

http://localhost/SteelBlue/examples/steelblue