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.

The second step is to check with the Perl Modules option in the control panel and make sure that DBI and DBD::MySQL modules are available. If not, you may need to either go through the process of importing them from CPAN or raise a support call with your hosting provider asking for them to be added.

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

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

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.

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

	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. The next step is setting up the cgi-bin directory - the first thing to do is to find out where the hosting provider has put it. 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.

# 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*
#

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
#

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
#

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

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.

With these three done in that 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> 

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 will need to ensure that the PERL5LIB environment variable is established within your shell environment in order to use the command line tools. This 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

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.

The 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 user 
     > (userid,username,upassword,ustatus,utype,uclass,uadded)
     > values(1,'wacs','badpasswd','A','F','admin','2010-03-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.

Warning

The details for how to setup WACS for use in a Web Hosting Provider's environment were new in 0.8.4 and are based on our own experience setting up PinkMetallic.com and may well be incomplete. Additionally some aspects of Wacs are not yet tailored to this kind of environment and are bound to cause issues. Please report any problems you find to us using the facilities on sourceforge or our email addresses.

There's a known issue with the security settings when you use the wacsimport and (probably) wacsxmlin. Once these have created the icons, they change the permissions of the owning directory to be accessible only by the user and group. This is not the correct strategy on a web hosting provider as their apache web server is not a member of any unix group in common with the shell user account. The quick solution to this is to run the following on the web document tree (usually under ~/public_html/ after each importation has taken place:

# cd ~/public_html
# chmod -R o+rX bigicons cache icons images wacs
#

Unfortunately there can be further issues when trying to use the WACS system in that many web hosting providers do not install all of the infra-structure that it needs, including packages like the netpbm tools which provide the image scaling and thumbnailing facilities we use extensively within WACS. It is quite possible to copy both the binary programs and the necessary shared libraries from another Linux host of similar architecture onto your space on the web hosting provider. The alternative approach is to compile the netpbm suite from source code and then statically link the resulting binaries. This is what we had to do to make the PinkMetallic.com site work. The commands below show what we did - the first command being to determine the CPU/runtime architecture being used - in this case standard 64-bit AMD/Intel EMT architecture, and the second to determine the distribution being used:

# uname -p
x86_64
# uname -r
2.6.18-128.1.6.el5
# mkdir ~/lib
# export LD_LIBRARY_PATH=/home/yoursite/lib
#

	Tip
	We understand this step is non-trivial and confusing and there's very little we can do about this other than to invite you to post on the wacs-users mailing list for help and advice. Each web hosting provider probably has a different combination and there is little else we can do other than offer to help as best we can.

This tells us (from experience) that we're dealing with a RedHat Enterprise Linux distribution running on a 64-bit AMD-style architecture processor. For that centos.org is the best place to find suitable packages for download - we selected two RPMs from one of their mirror sites: netpbm-10.35.58-8.el5.x86_64.rpm for the libraries and netpbm-progs-10.35.58-8.el5.x86_64.rpm for the tool binaries. We then used the rpm2cpio command to covert these rpm archives into more standard archive formats and then the cpio command itself to unpack the result.

# wget http://www.mirrorservice.org/sites/mirror.centos.org/5.4/o
s/x86_64/CentOS/netpbm-10.35.58-8.el5.x86_64.rpm
[...]
# rpm2cpio netpbm-10.35.58-8.el5.x86_64.rpm > netpbm-10.35.cpio
# cpio -ivudB < netpbm-10.35.cpio
[...]
# wget http://www.mirrorservice.org/sites/mirror.centos.org/5.4/o
s/x86_64/CentOS/netpbm-progs-10.35.58-8.el5.x86_64.rpm
[...]
# rpm2cpio netpbm-progs-10.35.58-8.el5.x86_64.rpm > netpbm-progs-
10.35.cpio
[...]
# cpio -iuvdB < netpbm-progs-10.35.cpio
[...]
#

Having done this we have the entire netpbm tree contained in a directory called usr under the current directory. The first command the wacs program we were trying to run (actually it was generate) complained about was pnmscale so we fetch the pnmscale binary from usr/bin/pnmscale and transfer that up to the web hosting provider and place it in our ~/bin directory. Once we've done that we run the ldd command on it which says:

# cd ~/bin
# ldd pnmscale
	libm.so.6 => /lib64/libm.so.6 (0x000000365ee00000)
	libnetpbm.so.10 => not found
	libc.so.6 => /lib64/libc.so.6 (0x000000365e200000)
	/lib64/ld-linux-x86-64.so.2 (0x000000365de00000)
#

The pertinent thing here is that libnetpbm.so.10 is the only library we need for pnmscale to work that isn't there. If we check back in our unpacked package, we should have that file as usr/lib64/libnetpbm.so.10.35. Since it's libnetpbm.so.10 that it's asking for, we transfer our local usr/lib64/libnetpbm.so.10.35 up to the hosting provider server as libnetpbm.so.10 using the ftp/sftp put command as follows:

sftp> put usr/lib64/libnetpbm.so.10.35 libnetpbm.so.10
Uploading usr/lib64/libnetpbm.so.10.35 to /home/yoursite/lib/libnetpbm.so.10
usr/lib64/libnetpbm.so.10.35                  100%  187KB  93.3KB/s   00:02
sftp>

If we now re-run the ldd command on pnmscale, we should now see that all the dependencies are resolved. The final test is to run the command itself, and it this case it's default action is to complain that you didn't ask it to do anything. All that remains now is to do the same procedure of copying up the other files from usr/bin that Wacs is asking for. We found we needed the following: pbmtext, pnmcat, pnmscale, pnmtojpeg, pnmtopng, pnmtogif, pngtopnm, giftopnm and jpegtopnm.

The first of the two final things we have to do is to check that everything under the ~/public_html/cache tree is publicly writeable (gulp!) because we share no groups in common with the web server. The second is to add the LD_LIBRARY_PATH variable to the environment used by the web server so that the netpbm commands actually work when invoked by the wacs commands themselves. Fortunately the dbienvvar and dbienvvalue variables originally added to enable Oracle to be supported can be used for this purpose. In the wacs.cfg file, set dbienvvar to LD_LIBRARY_PATH and dbienvvalue to the path to your library directory where you placed the libnetpbm.so.10 file; it's probably something along the lines of /home/yoursite/lib. You will also need to add a suitable entry in your .bashrc or .cshrc to set LD_LIBRARY_PATH for your shell.