This document describes how to quickly install ExSite Webware on a webserver in a conventional configuration.  It takes only a few minutes.  There are other ways to set up ExSite, but they will involve manually configuring some things;  details are given in the Advanced Installation Guide.

Note that the Quick Installation procedure described here is for ExSite version 3.6.

Synopsis

1. Download and unpack the base distro and a plugin distro in a convenient working directory on your server.
   
2. Copy the Makefile to your site's CGI-BIN directory.
3. Edit the Makefile to set your installation parameters.
4. Run "make exsite" from the CGI-BIN directory to install all of the code.
5. Run "make db" or "make dbtables" to configure your database.
6. Test your installation.
   

That's all there is to it.  Each of these steps is described in more detail below so you have a better understanding of what is happening.

Download

Before you can begin installation, you will need two code distos:

1. ExSite Base System - this is the kernel of the system
2. ExSite Plugins - this is a collection of plug-in components that can optionally be added to your site.  You will want to add some of these, but not necessarily all of them.
   

These are available from Exware Solutions if you are a supported customer, or from http://support.exsitewebware.com or http://sourceforge.net/exsite if you want the OSS version.

Each of the distros is a Gzipped Tar file (extension .tgz or .tar.gz).  The files usually have the version number in the filename; try to use ones with matching versions, or you may have compatibility problems.  Place these files into a working directory, and unpack them using commands like:

% tar -xzvf exsite3.6.0.tgz
% tar -xzvf exsite-plugins3.6.0.tgz

Now you will have two directories containing all of the code and other files that you will need, eg.

./exsite3.6.0
./exsite-plugins3.6.0

You need to know where you will be installing these files.  There are two locations that these files get installed into:

CGI-BIN	this is your web executables direcotry
HTDOCS	this is your HTML documents directory

If you are not sure where these directories are, ask your system administrator.  They can have slightly different names on different systems.

Configuring the Makefile

Change to your CGI-BIN directory, and copy the ExSite makefile to that location.  It is distributed in the base distro, in the "install" subdirectory.

% cp $BASE/install/Makefile .

The various configuration options are set at the beginning of the Makefile.  Edit this file using your favourite text editor, and set the options to appropriate values.

Pay particular attention to the following settings:

BASE_REPOSITORY - this is the location of the base distro that you unpacked (eg. exsite3.6.0).  You can give a full path, or a location relative to the CGI-BIN directory.

PLUGIN_REPOSITORY - this is the location of the plugin distro that you unpacked (eg. exsite-plugins3.6.0).  You can give a full path, or a location relative to the CGI-BIN directory.

DOCROOT - this is the location of your htdocs directory.  You can give a full path, or a location relative to the CGI-BIN directory.

PLUGINS - this is a list of plugins to install by default.  It is preset to a useful list, if you are not sure.

INSTALL - this is the installation method to use.  Two settings are meaningful:

cp -r	This creates private copies of all installed files.
ln -s	This allows you to share some files with other sites, and can also make it easier to upgrade sites by separating private files from system files.

DB_NAME, DB_USER, DB_PASS, DB_HOST - these are the connection settings for your MySQL database.

EXSITE_LOGIN, EXSITE_PASSWORD, EXSITE_NAME, EXSITE_EMAIL - these describe the default administrator account that should be created for you to log in to.

When your settings are satisfactory, save the file and exit the editor.

Install Code

Now you run "make" to perform the installation:

% make exsite

This installs all of the base code and all of the preselected plugins.  It prints out a lot of status messages, which may be helpful if something goes wrong.

If you don't want to install the plugins at this time, you can install the base code and plugins in separate steps, for example:

% make base
% make plugins

Alternatively, you can install plugins individually by naming each plugin you want:

% make PLUGIN_A
% make PLUGIN_B

After you have done this, the following things will be set up for you:

• ExSite kernel installed
• ExSite static files installed
• plugins installed
• configuration file setup and installed
  

At this point the system should run.  However, it will not do anything useful until you have a database.

Install Database

If your ISP has set up your database for you, then you only need to create your database tables.  If your are your own system administrator, you need to create your database first.

In the latter case, you should

% make db

This creates your database, defines the MySQL user and access permissions, and then installs your tables.  You need to be the MySQL root user to do this.  The Makefile will pause to explain this, and when you confirm, will want you to enter the MySQL root password to proceed.

If your database was already created for you by your ISP, then you only need to install your tables.  You will need your MySQL password to do this (you should have entered it into the Makefile, so check there if you forgot it).  Then run

% make dbtables

Test the Installation

The Makefile includes a simple test to ensure that the necessarily files were installed in the right locations:

% make test

This does not really exercise the system, however.  It only checks that the files exist.  A more comprehensive test is to access the files through your web browser, to see if the webserver is finding them correctly, and that it can connect to your database.  There is a simple test script you can visit in your browser to check:

http://www.yourwebsite.com/cgi-bin/exsite-test.cgi

Of course you should change "www.yourwebsite.com" to whatever is appropriate in your case.  With some servers, the name of the cgi-bin directory will vary, so check with your system administrator if you are unsure.  This script tries to print out helpful diagnostics if it detects any problems.

Reconfiguring

Your configuration settings are written to the file:

cgi-bin/conf/exsite.conf

You can edit this file to adjust or customize your configuration, including changing many default system behaviours.

Note that ExSite tries to auto-configure itself when it runs, to determine where its various parts are located, what the website/domain name is, and other server settings.  In less common server configurations, it may not guess these settings correctly, in which case you may need to manually specify the following settings in the configuration file:

• server.HTMLpath = the relative URL (no domain) to the base HTML documents directory that ExSite works from (empty string if using the base HTML docs directory for the website).
• server.HTMLroot = the server's disk path to the base HTML documents directory for the website (eg. "/var/www/html").
• server.CGIpath = the relative URL (no domain) to the base cgi-bin directory that ExSite works from (typically "/cgi-bin" or "/cgi" if using the base cgi-bin directory for the website).
• server.CGIroot = the server's disk path to the base cgi-bin directory for the website (eg. "/var/www/cgi").
• server.protocol = the webserver protocol (usually either "http" or "https").
• server.host = the site host name (eg. "www").
• server.domain = the site domain name (eg. "yourdomain.com").
• server.port = the server port number, if not the default.
• server.server = the full server URL, which is a combo of the protocol, host, domain, and possibly port parameters.

Installing new components

You can also use the same Makefile to install new plug-in components at any time.  From your cgi-bin directory, run "make" with the plug-in name as a parameter.  For example:

% make SlideShow

will install the "SlideShow" plugin.

% make SlideShow Gallery PhotoAlbum

will install those three plugins.

Reinstalling

To remove the current installation so you can reinstall, use:

% make clean

This will copy your current installation files into an Archive directory so that you can recover any special changes you may have made, and then removes all of your ExSite files.  It does not remove any published website files.  If you archive old installs multiple times, each will be archived in the archive directory of the install that followed it.

To completely wipe out the installation, use

% make veryclean

This also removes the Archive directories, so use with caution, since no trace of the previous install will be left.

After doing either of the above, simply re-do the installation as described above.