WebHost Installation: Steps
Prev Chapter 7. Installation On A Web Hosting Site Next

WebHost Installation: Steps

Preparation On Web Host

  1. The first step is to create a new folder under the web document tree (conventionally public_html) called wacs. Into this directory you need to copy all the components in the unpack_location/htmlbones directory and it's sub-directories, retaining the directory structure as found below htmlbones. There are a number of ways in which to achieve this and they vary enormously depending on your hosting provider, level of access at your hosting provider and equipment available to you locally.

  2. The second step is to check with the Perl Modules option in the control panel and make sure that DBI, DBD::MySQL and XML::Simple perl modules are available. If not, you may need to do one of three things: go through the process of importing them from CPAN, raise a support call with your hosting provider asking for them to be added or unpack them manually from the packages for the Linux distribution the web host provider is using (see notes in the section called “Final Notes For Web Hosting”).

The Wacs Code Itself

Due to limitations on what you can install, the ability to authenticate user accounts using the operating system tools cannot be implemented when using a Web Hosting Site. You will therefore have to use one of the other authentication techniques - storing user accounts in the database itself, using permanent access lists or enable all access at the WACS level and then use Apache's .htaccess files to demand a password before accessing those commands.

[Note]Note

Wacs 0.8.5 includes support for authenticating using user account stored in the database for the first time. This is a major new feature in the release and may still have some bugs, so please tread carefully and report any issues you find. Support for using Wacs on a web hosting site was added right at the very end of development work on the Wacs 0.8.4 series as we created our demonstration site, PinkMetallic.com

  1. The first step is to copy the Wacs Perl Modules into an appropriate place - our web hosting provider had already created a perl subdirectory of our account's home directory, so we used that. That probably makes sense even if it hasn't already been done for you as it wasn't on one of the other major web hosting providers we did an install for a consultancy customer on.

    # cd unpack_location
# cp modules/wacs.pm ~/perl/Wacs.pm
# mkdir ~/perl/Wacs
# cp modules/wacsui.pm ~/perl/Wacs/WacsUI.pm
# cp modules/wacsstd.pm ~/perl/Wacs/WacsStd.pm
# cp modules/wacsid.pm ~/perl/Wacs/WacsId.pm
#
    [Tip]Tip

    Note the change of case of the names; most command line ftp/sftp tools will allow you to specify a second name on a put command for the name of the file at the destination. Thus you can do: put wacs.pm Wacs.pm to do the name change as part of the transfer itself.

    Additionally if you want to include support for the PHP5 dialect of the Wacs API, you will also need to copy the following:

    # cd wacs-php_unpack_location
# mkdir ~/php5
# cp modules/wacs.php ~/php5/wacs.php
# cp modules/wacsui.php ~/php5/wacsui.php
# cp modules/XMLSimple.php ~/php5/XMLSimple.php
#

You can skip all of the bits about security and the pam modules as we'll be unable to use those aspects of the Wacs system on a web hosting service. We will instead either use a global allow on the wacs.acl file to allow everyone access or we will be using the database authentication method.

  1. The next step is setting up the cgi-bin directory - the first thing to do is to find out whether the hosting provider allows you to use one and if they have where the hosting provider has put it within your account's space. One major hosting company did not provide for a cgi-bin directory, instead requiring .pl extensions for each perl program. We built extensive support for doing this into the WACS 0.9.1 release - do not attempt to use an earlier release on a hosting provider who does not allow for cgi-bin directories.

    In the case of the provider we're using for PinkMetallic.com this is a sub-directory called cgi-bin under the public_html directory.

    In common with the packaged versions of Wacs, we're going to recommend putting the wacs scripts into a sub-directory of the cgi-bin directory when using a web hosting service. Here's what to do with cgi-bin hosting providers:

    # cd unpack_location
# cp index/wacs* ~/public_html/cgi-bin/wacs/
# cp models/wacs* ~/public_html/cgi-bin/wacs/
# cp presentation/wacs* ~/public_html/cgi-bin/wacs/
# cp retrieval/wacs* ~/public_html/cgi-bin/wacs/
# cp search/wacs* ~/public_html/cgi-bin/wacs/
# cp tag/wacs* ~/public_html/cgi-bin/wacs/
# cp security/wacslogin ~/public_html/cgi-bin/wacs/
# cp security/wacslogout ~/public_html/cgi-bin/wacs/
# cp security/wacspref ~/public_html/cgi-bin/wacs/
# cp manage/wacs* ~/public_html/cgi-bin/wacs/
# chmod 755 ~/public_html/cgi-bin/wacs/wacs*
#

    For those who use .pl extensions, do the following: 

    # cd unpack_location
# mkdir ~/html/apps
# cp index/wacs* ~/html/apps/
# cp models/wacs* ~/html/apps/
# cp presentation/wacs* ~/html/apps/
# cp retrieval/wacs* ~/html/apps/
# cp search/wacs* ~/html/apps/
# cp tag/wacs* ~/html/apps/
# cp security/wacslogin ~/html/apps/
# cp security/wacslogout ~/html/apps/
# cp security/wacspref ~/html/apps/
# mkdir ~/html/admin
# cp manage/wacs* ~/html/admin/
# chmod 755 ~/html/apps/wacs*
# chmod 755 ~/html/admin/wacs*
#

    You will then need to rename each command to having a .pl extension - as in: mv wacsindex wacsindex.pl in both the apps and admin directories

  2. As described above, the next step is to make copies of those wacs applications that are merely versions of existing applications with alternative default values. In most cases, this will be changing variables called either thumbsmode or vidmode as appropriate.

    # cd ~/public_html/cgi-bin/wacs
# cp wacsmodelpage wacsmpthumbs
# editor wacsmpthumbs
# cp wacsmodelpage wacsmpmini
# editor wacsmpmini
# cp wacsmodelpage wacsmpfull
# editor wacsmpfull
# cp wacsimgcats wacsvidcats
# editor wacsvidcats
# cp wacsimgcats wacsphotcats
# editor wacsphotcats
# cp wacsimglist wacsvidlist
# editor wacsvidlist
# cp wacsnewsets wacsnewvideo
# editor wacsnewvideo
# cp wacsshow wacsvidshow
# editor wacsvidshow
# cp wacsindex wacspage
# editor wacspage
# cp wacsimgselect wacsvidselect
#

  3. One additional step we have to take within the web hosting environment is to add symbolic links within the cgi-bin directory back out to the ~/perl directory in order that our web applications can pick up the Wacs perl modules. This is done as follows:

    # cd /home/yoursite/public_html/cgi-bin/wacs
# ln -s /home/yoursite/perl/Wacs.pm
# ln -s /home/yoursite/perl/WacsUI.pm
# ln -s /home/yoursite/perl/WacsStd.pm
# ln -s /home/yoursite/perl/WacsId.pm
#

    Once again if you also want to support the WACS PHP API, you'll also need to make the appropriate links so that the php applications can find the Wacs PHP modules. Here the location depends on what skin or code you're using and will need to be present in each directory in which you have Wacs-PHP API based applications. Assuming you're going to be installing the Simple Skin, this will be in a directory called simple within your public_html web document tree. This can be done as follows:

    # cd /home/yoursite/public_html/simple
# ln -s /home/yoursite/php5/wacs.php
# ln -s /home/yoursite/php5/wacsui.php
# ln -s /home/yoursite/php5/XMLSimple.php
#

Configuration

  1. This is one area where the procedure for a Web Hosting Site is significantly more complex than that for a conventional Wacs install as practically all of the entries related to database and file system locations (fsloc) will need tuning based upon actual layout of the account on the web hosting site.

    The first step is to create a suitable sub-directory for the wacs configuration files, ideally in the top level of your file space. If at all possible DO NOT put it in the web space directory as it contains passwords and other configuration items which you do not want everyone to be able to access. Next you want to find out the full path name of your top level directory, for which you use the pwd to the Linux/Unix shell.

    # pwd
/home/yoursite
#

    Your wacs configuration files will therefore live in /home/yoursite/wacs.d instead of the normal location of /etc/wacs.d. To make this change we have to go into the Wacs.pm perl module in the perl sub-directory and make the appropriate change. We could avoid this if the web hosting provider would allow us to establish the WACS_CONFIG environment variable in the appropriate virtual server configuration section in the apache web server. Our hosting provider would not do this for us so we have to work around that by modifying the default value in the Wacs.pm perl module itself. This is a little unfortunate in that it'll mean we have to modify this module each and every time there is a Wacs code update that affects it.

    Here's the appropriate change you need to make - what we've done here is copy the line setting the existing value called default_location1 and commented out the original version with a hash (# ) symbol at the start of the line. We've then edited the copy to have the new location on our web hosting provider's site there as the first default location:

    # Assumptions
my $fssep = '/';

# Where to find the WACS configuration
#my $default_location1="/etc/wacs.d";
my $default_location1="/home/yoursite/wacs.d";
my $default_location2="/usr/local/etc/wacs.d";
my $default_location3="/opt/wacs/etc/wacs.d";
my $default_specifier="WACS_CONFIG";
    [Note]Note

    If you're also planning to use the PHP5 version of the Wacs API you will need to make identical changes to the wacs.php file provided with that.

    The next step is to copy into this new wacs.d directory a sample wacs.cfg and wacs.acl file. We've provided a sample pair that will hopefully be a good starting point in the conf/WebHost sub-directory of the wacs source distribution. Please do make sure that you manually create at least each toplevel directory under your account's home area - ie run, cache, etc.

Database Setup

This is an area within the process where unfortunately we can't give you much help as it will vary between the different web hosting providers. With our provider for the PinkMetallic.com domain, there was a control panel for creating MySQL Databases which consisted of three steps: Create New Database, then MySQL Users: Add New User and finally Add User To Database. There was an additional option of Modify Databases which we had no cause to need at this point.

On another web host we worked on, when we created the MySQL database in the control panel, it gave us a database connect string to use to connect to the database server on which our instance is hosted. This required the use of the specified host URL with the -h option to mysql. We also had to include the server host specification in the connect strings in wacs.cfg.

With these steps done in the appropriate order, we got a MySQL database account we could log into using the following:

# mysql -u yoursite_wacs -p yoursite_wacs
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 206917
Server version: 5.0.81-community MySQL Community Edition (GPL)

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql>

Database Schema Creation

  1. login as the database user just created and run the table create SQL script from the creation directory of the wacs distribution. These scripts are called by a single creation script, the one for MySQL is called create_mysql.sql and that is usually the only option available on web hosting sites. In due course we may add support for pgsql into WACS and that is offered as an alternative by some web hosting providers. One hosting provider still had the older MySQL 5.0 version as their offering and we had only one minor problem with it (see the section called “Final Notes For Web Hosting”).

    To run this on MySQL 5.1 using the account created in the step above, you would do the following (the only difference for a web hosting service is that you probably have a yoursite_ prefix on the user and database names):

    % cd unpack_location/creation
% mysql --user=wacs --password=wacs wacs < create_mysql.sql
WACS Database Table Creation Script for MySQL
Commencing Table Creation:
  1. Photographer
  2. Vendor
  3. Sets
  4. Models
  5. Assoc
  6. Idmap
  7. Download
  8. Tag
  9. Conn
 10. Keyword
 11. User
 12. Attrib
 13. Notes
Tables Created - Committing Changes
Completed.
%

Support Scripts

The procedure here is almost exactly the same as above except of course that we cannot add things to /usr/local/bin and so we have to place them within our account's home directory.

# cd unpack_location
# cp -p tools/* ~/bin
# cp -p download/* ~/bin
# cp -p migrate/* ~/bin
#

Additionally you ideally want to ensure that the PERL5LIB environment variable is established within your shell environment in order to use the command line tools. The alternative is to put symbolic links in each directory to where the WACS perl module files are to be found. Setting the PERL5LIB environment variable can be done initially with:

# PERL5LIB=/home/yoursite/perl
# export PERL5LIB
#

To add it to your shell configuration so it is always established, you'll need to edit your shell start-up file (usually .bashrc in your home directory) and add the following line at the bottom of it:

export PERL5LIB=/home/yoursite/perl

Populate The Initial Database

[Note]Note

From WACS 0.8.4 onwards we've suppressed the Inserting Entries For... messages as they were playing havoc with the formatting on wacssetup. If you want to see them, simply edit the wacs.cfg debug section, look for the util_wacspop entry and set it to 1 or higher.

[Warning]Warning

These instructions describe Wacs release 0.8.6 and higher; previous releases had individual utilities for loading each database table and did not feature the attributes table at all. The attrib table is used extensively in Wacs release 0.9.0 and higher.

  1. The next step is to populate the vendor database with the sample records, which can be done with: 
    # cd unpack_location/populate
# ./wacspop vendors.xml
Inserting Entries For Site: ATKP
Inserting Entries For Site: AMK
Inserting Entries For Site: ATE
Inserting Entries For Site: SE
#
    Please contribute back vendor descriptions you create to be included in the next release.
  2. Next we need to preload the keywords database table so that the automatic tagging will occur correctly. We do this with: 
    # cd unpack_location/populate
# ./wacspop keywords.xml
[...]
#
  3. Next we need to load the photographers database with some initial example records, which can be done with: 
    # cd unpack_location/populate
# ./wacspop photographers.xml
[...]
#
  4. Finally we need to load the attributes database with the basic attributes we will be using for searches and markup: 
    # cd unpack_location/populate
# ./wacspop attrib.xml
[...]
#

Initial User Creation for Database Authentication

If you're planning to use database authentication on your site, there's a catch 22 situation to get around first when you're doing a manual install. That is that although you can edit and create users using the wacsusermgr web application, you can't log in to the system in order to use the application until an initial account has been created. This is not so much of a problem with a normal root account install as this will initially be set up for host authentication which can be used to login that first time, create a user account and then switch over to the database authentication method. For a web site hosting provider where the host authentication method doesn't work, it's a lot more problematic. We now offer two solutions to this problem.

In WACS 0.9.1 we introduced a new users.xml file that sets up three accounts for you - root, support and guest . These give you an example of each of the possible types of user account - admin, power and viewer. This is ideal for testing and familiarisation activities but you really MUST remember to change these accounts from their default passwords before opening the server up to the internet. Their initial passwords are Svjck981 for the root account, uKiFt126 for the support and freebie for the guest account. To add these accounts, run the following:

# cd unpack_location/populate
# ./wacspop users.xml
[...]
#

The other solution is to manually create the necessary user account using the SQL command line tool. Here is an example of how to do this:

# mysql -u yoursite_wacs -p yoursite_wacs
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 206917
Server version: 5.0.81-community MySQL Community Edition (GPL)

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> insert into wacsuser 
     > (userid,username,upassword,ustatus,utype,uclass,uadded)
     > values(1,'wacs','badpasswd','A','A','admin','2012-11-11');
Query OK, 1 row affected (0.00 sec)

mysql> commit;
Query OK, 0 rows affected (0.00 sec)

mysql> quit;
Bye
#

Once you've created this account you will be able to log in to a database authenticating WACS system and create other users through the Web GUI.

Prev Up Next
Chapter 7. Installation On A Web Hosting Site Home Final Notes For Web Hosting