This document describes how to manually install ExSite onto a web server. These steps are performed automatically if use use the Quick Installation procedure. They are described in detail here in case you need to customize that procedure for peculiar server setups.
ExSite has been installed and run successfully on Linux and OS X, but it should work on most Unix-y webserving environments. One of our developers even had it running under XP-Pro/IIS, although no real testing was done, so we doubt it was bug-free or feature-complete on that platform. It is distributed to work with MySQL, but other DBs can be used with modifications to the DB package (not included). As distributed, the following system specs are recommended:
* pre-installed by default on many Linux distributions.
The ExSite Base distribution encompasses the following important directories:
./cgi - contains all programs and libraries. All CGI programs are contained directly within the cgi directory; libraries are contained in subdirectories of the cgi directory.
./doc - documentation and help files.
./install - installation files.
You have a certain amount of flexibility in where you place the above groups of files, so ExSite can be reconfigured for a lot of different web serving environments. This section will outline a common basic installation that will configure a typical ExSite-based website. Later in this document, we will outline some alternative install procedures that can be used for other server configurations.
Basic installation has 4 steps:
Each of these steps is described in detail, below.
Note that you will be dealing with a number of different user identities, which could get confusing. Try to keep them sorted out in your head, to prevent login and authentication difficulties later:
Copy the contents of ./html in the ExSite distribution, to your own server's "DocumentRoot" directory. In the standard ExSite distribution, all html files are located in subdirectories named _ExSite and _Modules, so they should not overwrite any existing files in your server's DocumentRoot (unless you happened to have files of those names already there -- unlikely unless you are already running ExSite). For example,
% cp -r ./html/* /var/www/html
You will need to do this under a user ID with permission to write to the webserver directories, of course.
The above example is typical of an installation to the system webserver documents directory. The actual directory may vary from system to system. If your webserver is hosting multiple websites, then you will probably be installing to a "VirtualHost" web directory, instead of the system directory. In that case, the copy destination will be your virtual host document directory, which might be something like:
% cp -r ./html/* /home/my_website/public_html
Consult your system administrator, if you are not sure.
The ExSite CGI programs are those files in the ./cgi directory. They include page generation, publication, and administrator tools. They also include the kernel and dynamic content modules subdirectories, and a third subdirectory called the DBmap. (The DBmap is a mini-database that describes the schema, relational structure, and special web features of the primary ExSite database. It consists of a handful of tab-delimited text data files.)
To install your CGI programs, simply copy all of the contents of the ./cgi directory in the ExSite distribution (including subdirectories), to your system ./cgi-bin directory, eg.
% cp -r ./cgi/* /var/www/cgi-bin
(If you are running in a shared webserving environment, the target directory will be somewhat different, for example /home/my_website/public_html/cgi-bin. Consult your system administrator for the specifics on your server.)
In order to publish your pages, the webserver needs to be able to write files into the site's htdocs area. This is done by the publish.cgi program, which must be compiled now. Change to the cgi-bin directory, and execute the command:
% cc -o publish.cgi publish.c
Now that you've created the publish.cgi program, it must be given permission to write pages into the htdocs area. There are two methods for accomplishing this:
Set the setuid bit on the publish CGI program, so that it can write to the htdocs directory:
% chmod +s publish.cgi
Warning: your user identity should be something other than root. Setuid root programs are automatically rejected by Apache.
Use Apache's suEXEC feature to allow the site's CGI programs to run as a user ID that can write to the htdocs area.
Configuration of suEXEC is beyond the scope of this guide, but if your server is running with suEXEC, then you do not need to modify your publish.cgi program at all. Your server must be configured so that your site runs under a user ID that can write to the htdocs area, however.
Most webservers come with suEXEC disabled by default, so Method 1 is more likely to work if you are not sure.
If you are installing onto a 64-bit server, you will need to compile a special encryption engine, since the pure-Perl encryption engine only works on 32-bit machines:
% cc -o crypt_tea crypt_tea.c
Two database installation/configuration scripts are provided with the ExSite distribution, in the install directory. You may use either one:
Select which of these scripts you want to use to initialize your database. The last line in each script creates an ExSite user, which allows you to log in. You should edit this line (using any text editor), to change the login name and especially the password to your website user identity.
If your database was created in advance by your system administrator or ISP, you can skip this part.
Log in as the mysql root user, and create the database:
% mysql [-h IP_ADDR] -u root -p
Enter password: ******
mysql> create database my_database;
You will also need to create a MySQL user that can connect to this database and make queries. For instance, this command creates a user with the minimum permissions required by ExSite:
mysql> grant create,select,insert,update,delete on my_database.*
to username@host identified by 'password';
(my_database, username, host, and password should be changed to whatever is appropriate. host can be set to "localhost" if the MySQL server is on the same machine as the webserver.)
Strictly speaking, create priveleges are only required to run the initialization script, below. If you run the initialization script (described below) as the MySQL root user instead of as the username you just created, then you can leave create off of the list of priveleges granted in the above statement.
Note: If you are running MySQL version 4.0 or higher, you will probably need to add "lock table" to the list of permissions in the grant command, above.
Once your database is ready to go, start up MySQL:
% mysql [-h IP_ADDR] -u mysql_username -p
(The -h IP_ADDR argument is not required unless your database server is on a different machine.) mysql_username should be the normal mysql user ID that ExSite will connect to the database with (the same one you granted permissions to, if you created the database yourself). After you enter your MySQL password, you can create your database with the following commands:
mysql> use my_database
mysql> source exsite-demo.sql
(Use the exsite.sql script if you don't want to preload the database with sample content.)
Verify: Once you have run the database script, a show tables; command should return something like this:
mysql> show tables;
| Tables_in_db |
| article |
| attribute |
| content |
| content_data |
| member |
| member_site_link |
| page |
| section |
| searchterm |
| searchurl |
| service |
| trash |
12 rows in set (0.00 sec)
At that point, type quit to exit MySQL.
Due to timestamp incompatibilities between versions of MySQL, you need to inform ExSite which version of timestamps you are running with. If running MySQL v4.1 or higher, be sure to add the following configuration setting to your conf file (see next section):
timestamp_format = text
The default is timestamp_format=num, which is compatible with older versions of MySQL. At some point, the default can be expected to change, so it may be worth explicitly adding the configuration, regardless.
The file ./cgi-bin/exsite.conf contains various configuration parameters that control how ExSite behaves. The most important ones from an installation standpoint are the parameters for connecting to the database. These parameters you will need to modify (using any text editor) are:
server.db.name = your_database_name
server.db.user = your_mysql_user_name
server.db.pass = your_mysql_password
server.db.server = your_mysql_server
Your MySQL server can be set to "localhost" if it runs on the same machine as your webserver. More configuration options are described below.
To test your setup, point your browser to the exsite-test.cgi program in your cgi-bin directory. The URL will be something like:
This simple test program will attempt to connect to your database and execute a few rudimentary queries to verify that it can communicate with it and retrieve meaningful results. It will report on failures and suggest possible solutions. If all tests pass, it will give you a link to log in.
Note that it may complain about missing plug-ins, if you have installed just a base distro with no plugins.
If you reset your login name and password, as instructed above, then you can login using the data you provided. If not, then you can login using the default username "admin" and password "password". Obviously these are insecure and they should be changed. (Both can be changed using the My Profile tool on the administrator web-top. However, once you do this, your current login identity becomes invalid, and you will have to login again to re-authenticate.)
If you used the exsite-demo.sql database configuration script, then you will have a full set of sites and pages to test other aspects of the system. For instance, after logging in to the administrator web-top, use the "My Website" application:
The following configuration steps are optional, but may be useful in some cases:
If you would like to be able to read the HTML documentation through your website, then you must copy or symlink the ExSite doc directory somewhere into your HTML documents directory. To keep it out of the way of your regular site directories and files, you can place the help files under the _ExSite subdirectory in your HTML documents directory, eg.
% cd DOCUMENT_ROOT/_ExSite
% cp -r EXSITE_DISTRO_DIR/doc help
% ln -s EXSITE_DISTRO_DIR/doc help
Then, add (or modify) the line in your cgi-bin/exsite.conf file pointing to the help file location:
help_url = /_ExSite/help/index.html
NB: the symlink option only works if the followSymLinks option is enabled for your website.
The file cgi-bin/exsite.conf can contain many configuration parameters (review the source code of cgi-bin/ExSite/Config.pm for details). Some of the ones you may want to set or change immediately:
site.name = your_website_name
site.identity_cookie = the name of the cookie that holds login info
site.administrator = your_email_address
ExSite attempts to auto-configure itself to determine details such as host/domain info, protocols, and diskpaths and URLs to its document and cgi directories. If your installation or server configuration is a little irregular, then ExSite may have difficulties auto-configuring itself, in which case you can help it out by providing configuration values for any of these parameters:
You can specify any of the above that need to be explicitly specified. If you want to manually specify all of them, then disable auto-configuration entirely:
server.auto = 0
You can define a site logo that will be used in certain generic situations (eg. login screens). Simply specify the logo HTML (typically an
<img> tag) in the site.logo parameter:
ExSite can automatically log events and transactions to simple text logfiles, which is handy for monitoring system use, profiling, debugging, auditing, and collecting stats. There are three logfiles:
Each log has a logging level from 0 (log nothing) to 3 (log everything). Generally speaking, log level 1 records errors (task could not be completed), level 2 records warnings (task had problems, but they were worked around), and level 3 records informational diagnostics (task had no problems, but recorded a benchmark in its progress). Set the log level you want to use for each log in the exsite.conf file, eg.
# record database errors and warnings
log.db = 2
# record CMS errors only
log.cms = 1
You can also specify the logfiles themselves (the defaults are db.log, cms.log, diag.log), eg.:
log.logfile.db = /var/log/exsite/db.log
log.logfile.cms = /var/log/exsite/cms.log
log.logfile.diag = /var/log/exsite/diag.log
(If you don't specify the path to the logfiles, they will be written to the cgi-bin directory.) You should create the log files and ensure that the webserver has permission to write to them, eg.
% touch db.log
% chmod 666 db.log
Logs can be viewed online using the exsite_log.cgi program.
This section outlines a number of variations on the general install procedure, above.
The danger here is that you don't want to overwrite existing files in the site's htdocs or cgi-bin directories. The easiest way to do this is to place ExSite into a subdirectory of the existing site. In other words, copy ExSite's ./cgi files to cgi-bin/exsite/ in your website's area. Similarly, copy ExSite's ./html files to html/exsite/ in your website's area. (You can use any subdirectory name you like, although it is better for autoconfiguration if you use the same name in both the cgi-bin and html directories.)
ExSite attempts to auto-configure itself, so it may be able to automatically find its parts and know to confine itself to these subdirectories (including when publishing). Warning: as there are many ways to configure sites and servers, there is no guarantee that ExSite will auto-configure itself correctly. Always back up your files and perform tests before publishing, as there is a chance that it could overwrite existing files.
Say you are managing many different websites, but they are all hosted on the same server. You would like to use ExSite to manage many/all of them, but you don't want to have to install (and update) it many different times. There are several ways for multiple websites to share a single installation of ExSite:
For instance, you can install the kernel files (./cgi/ExSite/...) in a location that is accessible to all sites, such as in the Perl system library directories (eg. /usr/lib/perl5/site_perl). If you want your dynamic content modules to be accessible system-wide, then install them similarly. To keep dynamic content modules restricted to particular sites, install them under each site's cgi-bin/Modules directory only. You will still have to install the .cgi files into each site's cgi-bin directory.
Alternatively, keep your ExSite distribution in its own repository, and set up symbolic links to it from each site. Then a single update of the repository will automatically bring all sites up to date. Your sites must have the FollowSymLinks option enabled for their cgi-bin directories for this to work.
Whether or not you share the ExSite code between your sites, you also have the option of sharing the same database. The advantages of this are better sharing of computer and human resources, since single accounts can access and administer multiple sites. The disadvantage is that each site's data is not clearly separated/isolated from the others', which may be a security or reliability concern.
To share a database, simply use the same database configuration parameters in each site's exsite.conf file.
The following plug-ins are useful for a minimal system:
The following optional plug-ins are popular, and do not require any special database extensions, which makes them easy to install:
Other plug-ins have specialized functions and may require extending the base system's database (see below).
Each plug-in is distributed in a set of directories:
./cgi - contains all programs, libraries, and configuration files required by the plug-in. The subdirectory structure matches that of the base distribution. In the simple case, there will be only a ./cgi/Modules/[PLUGIN].pm file.
./html - contains any static files that may be served to the client (eg. images, stylesheets, help files, etc.)
A plug-in bundle may include multiple plugins, each in its own subdirectory that is organized as above.
Copy the files under ./cgi to the matching directories in your main installation's CGI-BIN.
Copy the the files under ./html to [HTDOCS]/_Modules/[PLUGIN-NAME]/. For example, when installing the Foo plugin:
cp -r ./html/* $HTDOCS/_Modules/Foo
The simple utility script install-dcd.pl performs the above procedure. This script is included in the bin directory of the ExSite Base Districution, and should be executed from the cgi-bin directory of your site. It prompts you for your preferences, and provides defaults in many cases. Here is an example of how it works:
This script installs a dynamic content driver (DCD) into a website.
We will install a dynamic content module from your local module
repository. This is a directory containing copies of all the dynamic
content modules that are available to this system. You must provide
the repository base path.
Base path to modules: [/home/exware/exsite-plugins]
The available dynamic content modules are:
Which module are you installing? CMS,Gallery,Member,MySite,Security,SimpleMenu,WebDB
Install method ('copy' or 'symlink'): [symlink]
We are going to install CMS,Gallery,Member,MySite,Security,SimpleMenu,WebDB into
using the symlink method.
If the plug-in distrubtion includes any files under ./cgi/dbmap/..., then it extends the database, and extra database setup will be required. If your plug-in does not include any special instructions, the following procedure is usually sufficient.
Each regular file in ./cgi/dbmap/* corresponds to one new table in the database. Ensure that these files have been copied to the matching directory in your CGI-BIN area.
There may also be two dot-files in ./cgi/dbmap/*: .datatype and .table. These should be appended to the matching files in your CGI-BIN area.
With the above files in place, you can generate a new database create script with the following command executed from your CGI-BIN directory:
perl -e 'use ExSite::DBmap; $d=new ExSite::DBmap(name=>"dbmap"); \
$d->make_sql_create_script;' > make.sql
Alternatively, use the makesql.pl utility script in the bin directory of the ExSite base distribution:
./makesql.pl > make.sql
However, the latter create script will include a command to insert a new admin user at the end of the script. Delete that.
The make.sql script contains all of the MySQL CREATE TABLE commands you need to generate your entire MySQL schema. In practice, you don't want to create all of your tables again, but the create script should use the "CREATE TABLE IF NOT EXISTS..." syntax, so there should be no harm in running it on an existing database. However, it is always a good idea to back up your database before doing any work like this.
With your database backed up, you can create the new tables inside MySQL by simply running the create script you just made:
mysql> use my_db
mysql> source make.sql
If the plug-in distrubtion includes any files under ./cgi/conf/..., then it has its own configuration files. These files may need to be edited to get useful behaviours, but the details will vary between plug-ins. Consult the files in question for details.