Wacs Installation Guide

This book is an installation guide for WACS site managers or system administrators seeking to install the WACS environment on their systems. It does assume a certain amount of familiarity with the normal processes of installing software packages on your systems; the sections on manual installation in particular also assume a basic knowledge of using the Unix operating system (or any other future supported OS platform). It also provides an overview to installing the WACS environment on a web hosting site using an environment like cPanel.

To get the best from this book, you should ideally be familiar with the basic user interface of the WACS applications themselves - the WACS User Guide would be an ideal primer for this and should introduce you to many of the concepts and tools being used here. There is also no substitute for using a real WACS site to get a general feel for how things work and are laid out. Our demonstration site is available at PinkMetallic.com and provides an opportunity to try WACS hands-on.

The task of installing WACS onto a new server system consists of a number of distinct steps; these are:

Some of these topics will be mentioned briefly here and will be covered in more depth in other guides in the WACS documentation set.

For copyright/licensing reasons, the example images feature sets from photoshoots by the main developer of WACS (Beaky) and a friend of his. These sets are available at our demonstration site, PinkMetallic.com where you can experience WACS in action. Currently access to PinkMetallic.com is free, but we may at some point in the future make a small charge for access if it doesn't receive the revenue we hope for from referrals.

If you are using either the RPM/DEB packages of the WACS applications, or the easyinstall script, and are using the default applications (MySQL in particular), the prerequisite applications will be automatically installed if they are not already present. If not, or you are using a different database (Oracle, or another like PostGres SQL), you will need to install these applications first as detailed in the table below and then follow the manual install steps:

Note

This feature was new in Wacs 0.8.1 and is currently available for Fedora 10, 11 and 12 based systems using the RPM package manager and for Ubuntu 8.10 LTS, 9.04 and 9.10 systems using the DEB packaging system. It is our hope to extend the packaged software approach to include other platforms in a future release. While we do not prepare packaged versions for older releases of Fedora and Ubuntu, we do not remove support from them from the packaging build files (.spec for Fedora, debian/ for Ubuntu), so you should be able to recreate packages suitable for use with earlier releases using the package build tools for your platform.

	Warning
	Package support for Fedora 10 and Debian 8.10 LTS will be dropped at the next release but replaced with Fedora 13 and Debian 10.04 LTS.

Where available for a given distribution and release, there are a number of WACS RPM or .deb packages you can make use of to install the WACS system. If you are using one of the more sophisticated package managers (yum, etc), you need only ask it to install the main wacs package and that tells the package manager what other components it needs to complete the install. This will bring in both the system packages needed - web server, database, perl libraries, etc - and the other parts of the WACS system needed for a working installation. If you are using one of the simpler package managers (rpm etc), it will complain about absense of the required packages until all the dependencies have been installed manually.

Since sourceforge.net doesn't yet seem to support YUM or debian repos properly you will have to download the requisite WACS packages manually in order for the install to proceed. We are working on a Personal Package Archive (PPA) area on launchpad.net for Ubuntu .DEB packages which we hope to launch shortly. Please watch the WACS web sites for more details.

	Warning
	In order to conform to the the Fedora packaging guidelines, quite a few of the file locations are different on the packaged version of WACS, from that created by the easyinstall script or manual process. It shouldn't cause problems, but you do need to be aware of it, particularly if moving a configuration file between releases.

The easyinstall script was our pre-packaging approach to installing WACS and can still be used on Fedora and Ubuntu distributions although now it is mostly useful for installing on older versions of Linux that are not supported directly by the packages we create. As of WACS 0.8.5, the packages are gaining maturity and are probably a better option than the easyinstall command, although it should nevertheless work fine. Additionally easyinstall will prove harder to upgrade than the packaged solutions. Since Wacs 0.8.4, the packaged versions of WACS do include the wacssetup configuration tool to provide a web interface to what easyinstall does but it is fairly new and may still have bugs, so easyinstall is a useful second option if you run into trouble.

This the only option available for any kind of unsupported operating system platform and on a web site hosting provider where you have no root system administrator access and no control over the filesystem layout. The instructions later in this guide take you through all of the tasks needed step by step. This does assume some basic familiarity with command line operation of the Linux/Unix environment and a reasonable knowledge of the software installation policies of the operating system in question. In the case of a web hosting provider, you will need some familiarity with their setup tools and utilities.

The first step obviously is to download the appropriate packages for the operating system release, version and processor platform that you intend to run it on. Where a package contains noarch that means that it is suitable for any processor architecture running that distribution of Linux. Currently RPM packaged versions are available for Fedora 10 (labeled fc10), and Fedora 11 (labeled fc11) and DEB packaged versions for Ubuntu 8.10 and 9.04. For more information on using the Ubuntu DEB packaged versions, please see the section called “DEB Installation Steps”

For an initial WACS installation (in this example for release 0.8.5 on an x86_64 machine running Fedora 10), you will probably want the following packages:

If you also wish to make use of the Wacs-PHP API, the Web 2.0 demo or the Simple Skin sample web site, you will also want the following files:

If you plan on making use of the download toolset to connect to subscription sites for automatic downloads (although do be aware that only a very few sites are supported so far), you will also want to get the package called wacs-download-0.8.5-1.noarch.fc10.rpm. You may also wish to download one of the two versions of the documentation package: wacs-doc-pdf-0.8.5-1.noarch.fc10.rpm or wacs-doc-html-0.8.5-1.noarch.fc10.rpm - you can always access the same documentation direct from our sourceforge web site.

Once you've downloaded the right packages, you need to gain the appropriate privileges and install the packages. There are any number of ways to do this, and you can pretty much use any of them; the example below uses the command-line based yum package manager:

# yum install --nogpgcheck wacs*.rpm
[...]
#

It is also possible to do this with the file manager, right clicking on each package file and choosing Install Package. The order on this is a bit tricky, but if you start with wacs-core and wacs-hostauth, then do the other packages and finally do the main wacs package, this should work out OK.

Once the packages, and their dependencies, have been installed please confirm that both the Apache 2 Web Server (httpd) and the MySQL Database Server (mysqld) are enabled and running. In the GNOME desktop, the System -> Administration -> Services menu will take you to the Service Configuration screen where you need to both enable and start httpd and mysqld if these are not shown as currently running. If you prefer using the command line, the following steps will do the same task:

# /sbin/service httpd start
Starting httpd:                                    [ OK ]
# /sbin/service mysqld start
Starting MySQL:                                    [ OK ]
# /sbin/chkconfig --levels 345 httpd on
# /sbin/chkconfig --levels 345 mysqld on
#

The final system configuration step before starting work on getting WACS configured is to ensure that SELinux is running in a reduced mode that will not block the WACS components from working. This is only an issue on Fedora and other Red Hat based releases at present. We hope to have this resolved by the next release of WACS. You can determine the current mode of SELinux using the sestatus command:

% /usr/sbin/sestatus
SELinux status:                 disabled
% 

To change the normal operational mode, you need to edit the file called /etc/sysconfig/selinux and change the line which reads SELINUX=enabled to either SELINUX=permissive (generates big log files and slows machine but allows for SELinux to be turned back on later more easily) or SELINUX=disabled (which disables it completely but can cause problems in the future if you want to switch it back on). You will also probably want to disable it immediately rather than doing a reboot before you can continue working on WACS - to do this, become root and run the following:

# /usr/sbin/setenforce 0
setenforce: SELinux is disabled
#

You can check this change has taken effect by using the sestatus command again.

The first step obviously is to download the appropriate packages for the operating system release, version and processor platform that you intend to run it on. Where a package contains all that means that it is suitable for any processor architecture running that distribution of Linux. Currently DEB packaged versions are available for Ubuntu 8.10, 9.04 and 9.10, while RPM packaged versions are available for Fedora 10, 11 and 12. For more information on using the Fedora RPM packaged versions, please see the section called “RPM Installation Steps”

For an initial WACS installation (in this example for release 0.8.5 on an x86_64 machine running Ubuntu 9.04), you will probably want the following packages:

If you also wish to make use of the Wacs-PHP API, the Web 2.0 demo or the Simple Skin sample web site, you will also want the following files:

If you plan on making use of the download toolset to connect to subscription sites for automatic downloads (although do be aware that only a very few sites are supported so far), you will also want to get the package called wacs-download_0.8.5-1.all.deb. You may also wish to download one of the two versions of the documentation package: wacs-doc-pdf_0.8.5-1.all.deb or wacs-doc-html_0.8.5-1.all.deb - you can always access the same documentation direct from our sourceforge web site.

Once you've downloaded the right packages, you need to gain the appropriate privileges and then install the packages. There are any number of ways to do this, and you can pretty much use any of them; the examples given below use the desktop file manager and the gdebi installer. We have not used the synaptic package manager in the illustrations because that only really copes with software provided by the main Debian repositories. Unfortunately sourceforge.net does not, as we are writing this manual, support the creation of package repositories.

As it is the GDebi is configured to be the first action listed on the actions menu in the GNOME file manager as installed on Ubuntu. You get to this by right-clicking on the downloaded packages and choosing Install With GDebi . The order on this is a bit tricky, but if you start with wacs-core and wacs-hostauth, then do the other packages and finally do the main wacs package, this should work out OK.

Here we have all of the Wacs packages for Ubuntu/Debian downloaded onto our desktop and we start work with wacs-core_0.8.5-1_all.deb . We right-click on it's icon and choose Open with “GDebi Package Installer”. Once selected we're told we're looking at Package: wacs-core and that it “Requires the installation of 28 packages”.

While this 28 packages figure may sound high, it's what is actually needed for all the Wacs packages and these packages will be requested by whichever Wacs package is installed first. Similarly, if you've already installed any of these prerequisite packages on behalf of another application, the number needing to be installed now will be greatly reduced. What we are installing here are things like the apache 2 web server, the php5 programming language, the MySQL 5 database and so on. This also attempts to install all the various Perl and PHP modules we use for database access and the like. Currently it will install MySQL 5 server as a dependency although you can still use Oracle as an alternative back end.

We click on the Install Package button and an additional pop-up box appears saying Installing dependencies.... This part of the installation procedure can actually take quite a while because on a normal Debian desktop install many of the requested packages will not be available locally. It will therefore make a connection to the internet software repositories and download the likes of MySQL 5, apache 2, Php 5 and the perl modules required.

Tip

If you're on a dial-up internet connection, or have a seriously bandwidth limited broadband connection, you might wish to insert an appropriate DVD-ROM of Debian packages and configure the repositories used to include the local DVD-ROM as well. Of course this may or may not work depending on whether any upstream updates to those packages have been issued. An alternative would be to manually install the MySQL 5 server, Apache 2 web server and the PHP 5 language packages first from the DVD-ROM. This would then just leave the small Perl and PHP module packages still to be installed.

However, you'll notice that confusingly it doesn't show any progress which is unfortunately due to the fact that the pre-requisite MySQL package has actually prompted for some user input. If we click on the arrow to expand the Terminal window, we see the actual problem:

As you can see, it's actually prompting for a new password for the MySQL root user, which we can either enter or just press return to ignore. Generally setting a root password on the MySQL root user is an extremely good idea... With this message acknowledged, the install should actually start making some progress.

	Note
	If you already had the MySQL 5 server installed, and the MySQL root user password was set, the installation may well have proceeded automatically with no intervention required at all.

If you didn't choose to set a password, it'll prompt you for it again. If you did, it may well prompt you to enter that password to enable what you're working on. Once the dependencies have all be installed, the wacs-core package itself will be installed last. Finally we should see the message Installation finished but of course this is merely for wacs-core - the installation of the Wacs environment as a whole is not yet complete.

We then need to repeat this installation process with each of the other packages from the wacs suite, with wacs-hostauth next and the package called just wacs with it's version number last. The reason for this is that the wacs package is the “glue” that holds all the parts of Wacs together. In due course we'd hope you could merely install the wacs package itself and have all the pre-requisites automatically installed. Unfortunately the current package managers that do the dependency resolution all steadfastly refuse to include other manually downloaded packages in that dependency resolution process, and so it fails. As soon as sourceforge.net starts offering the ability to create package repositories, or we can get Wacs accepted into the repositories of the major distributions, these problems should all disappear.

As each package is installed, you should see this kind of message. Once they're all done, you should be ready to proceed to the next step, which is to get various pieces of infrastructure to start automatically when the system boots and the initial database prepared.

The normal action of the RPM/DEB packages is to create a user account to hold all the datafiles, typically called simply wacs. Unless you choose to do otherwise, the images and video clips loaded into the WACS system are normally stored in the home directory of this account. For obvious reasons, the security on all the Wacs directories are locked down pretty hard, so you will need to pay attention to it. A new group also called wacs is created and initially the wacs and web server owner account are added to this. If you wish to read the documentation, samples and configuration files without always having to become the superuser first, you can simply add your own username to the wacs group.

There are a number of ways to do this including using the System->Administration->Users and Groups option or you can do it in the shell as root with the usermod command. Since the interface on Users and Groups GUI is very different between different distributions and versions, we're going to stick with the command line method as that is portable. To do this you use the usermod command if you're using a superuser shell, substituting the your_name with your user name:

# usermod -a -G wacs your_name
#

If you're using Ubuntu you can also do it directly using the sudo command:

# sudo usermod -a -G wacs your_name
[sudo] password for your_name:
#

	Warning
	After you've added yourself to the wacs group, the change will almost certainly not take place within the current session. You will have to log out and log back in again for your membership to be recognised. The groups command lists the groups you are currently in; when this list includes wacs, things should be working - when it does not, they won't be!

The first step of the process is where wacssetup makes sure you actually have the rights to do the things you're asking it to do. So it asks you for the root password to the system. If you're on an Ubuntu box and haven't set a root password, you can use your own account name and password providing you have sudo privilege to manage the system.

The second screen asks you to confirm the details of the database wacs is going to use. In almost all cases, apart from giving the database root password (if set), you should probably just accept the defaults. The choices are here primarily to highlight to you what is actually going to be used.

Note

Merely changing the password here from the default will not prove completely successful (yet), as the configuration file wacs.cfg has to be updated to match it. If you do change it here, you should log in on a terminal window before progressing to the next screen and change the entries in the database section of the wacs.cfg config file as well. Choosing a new password in wacssetup will ensure the database is setup with the new password from the start, but the last step of wacssetup will fail if the password wacsetup is using differs from that given in wacs.cfg (which is usually to be found in /etc/wacs.d/wacs.cfg).

This step creates the basic database structures and user account. There's not really much to say about this apart from a mention that if this fails for any reason, take a look at the section called “Installation Troubleshooting” and Chapter 10, Troubleshooting for help and guidence on what to do next.

This step creates the WACS specific database structures, known as schemas for each of the things it mentions. At this level, even if you're not planning on using facilities like vendors and photographers, at least the data structures need to be present, even if there's no data in them.

At this step you have to decide what sample data you want pre-loaded into the Wacs system. Our advice would be that unless you have an alternative set of keywords that you've developed yourself, you're almost certain to want to preload the Keywords schema under almost all circumstances. The vendors list is definitely useful for private collectors and is probably also of some use to website operators who might wish to earn additional revenue through cross-referal commissions. It also offers some examples of how to configure the download system. The photographers database is probably of the least use unless you're either a collector using sources that provide that information, or a website owner planning to offer that search feature at some point. That said it's small and relatively harmless, so including it isn't a big problem.

The sample model records are a rather different issue as these really are NOT suitable for inclusion on any kind of publicly accessible system. The sets and videos mentioned may be licensable for commercial use - contact Wacs developer Beaky for more information. These are however very useful introductions to how model records work and will significantly aid you in getting used to using and managing the Wacs system. We hope to shortly be able to provide some of the sets mentioned for download so you can set up a server with an initial data set.

... and that basicially is it. Wacs is installed and the initial system up and running. Although we've covered it else where (most notably in the User Guide, the next section will cover what happens when you click on the click here link that first time.

So... you've installed the packages, you've setup the database and your Wacs server is ready for use. But what exactly should you expect?... this section just guides you through what that first connection to your newly install system should look like.

At this point you're probably thinking Hey, I thought you said the server was ready? Why's it asking me more questions?. Well, remember Wacs is a sophisticated system that tries very hard to be as secure as possible because of the nature of the material it's designed to hold. Although you may not be familiar with it yet, this is actually the start of just about each and every new session with Wacs. This message is intentionally cryptic so that it does not immediately indicate what the system is. You just need to click on the login here link to proceed.

Here it's asking for your username and password - normally these are the same ones as you'd use when connecting to the server itself - nothing special.

At this screen all you really need to worry about is ticking the box consenting to viewing adult material (although there probably isn't any actually there yet). Then just click Complete Sign-On and you're there!

Yes, this is actually a perfectly working Wacs system! It just looks very spartan without any actual data to present. If you look through the model indexes, you should find empty pages for Kaz B, Roxanne and Sabrina if you installed the sample model records.

If you run into problems during the installation, there's a whole chapter (Chapter 10, Troubleshooting) which takes you through many of the common pitfalls and problems. This covers both installation issues (the section called “Installation Troubleshooting”) and general issues (the section called “General Troubleshooting Tips”).

The next step is to add some data but that is such a big topic that there's a whole separate guide about that! Go take a look at the Administration Guide....

Connect to the database as the root user, giving the password as appropriate; if you've not set one the default is blank so just press return when prompted. You then create the database and the user account (once for each place you might be coming from), give access to that user account to the database, flush the contents and then quit. Here's a sample conversation - you obviously need to replace the 'myserver.example.com' with whatever your real fully qualified domain name is. You might also wish to choose a more secure password, but do remember you need to change it in /etc/wacs.d/wacs.cfg (dbpass and phpdbconnect variables) as well or it just won't work.

Here goes:

# mysql -u root -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 80
Server version: 5.0.45 Source distribution

Type 'help;' or \h for help. Type '\c' to clear the buffer.

mysql> CREATE DATABASE wacs;
Query OK, 1 row affected (0.03 sec)

mysql> CREATE USER 'wacs'@'myserver.example.com'
    -> IDENTIFIED BY 'wacs';
Query OK, 0 rows affected (0.08 sec)

mysql> CREATE USER 'wacs'@'myserver'
    -> IDENTIFIED BY 'wacs';
Query OK, 0 rows affected (0.00 sec)

mysql> CREATE USER 'wacs'@'localhost'
    -> IDENTIFIED BY 'wacs';
Query OK, 0 rows affected (0.00 sec)

mysql> GRANT ALL ON wacs.* TO wacs;
Query OK, 0 rows affected (0.00 sec)

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

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

mysql> QUIT;
Bye
#

The next step is to log in as the wacs user account you just created and run the SQL scripts that create the various database tables. There are scripts provided for both MySQL 5 and Oracle 10, but this example is based upon using the MySQL 5 version. These should be found in /usr/share/wacs/creation/MySQL5.

# cd /usr/share/wacs/creation/MySQL5
# mysql -u wacs -p wacs
Enter password:
Welcome to the MySQL monitor.  Commands end withh ; or \g.
Your MySQL connection id is 82
Server version: 5.0.45 Source distribution

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> source create_mysql.sql
WACS Database Table Creation Script for MySQL
Commencing Table Creation:
  1. Photographer
Query OK, 0 rows affected (0.23 sec)

  2. Vendor
Query OK, 0 rows affected (0.01 sec)

  3. Sets
Query OK, 0 rows affected (0.01 sec)

  4. Models
Query OK, 0 rows affected (0.02 sec)

  5. Assoc
Query OK, 0 rows affected (0.01 sec)

  6. Idmap
Query OK, 0 rows affected (0.01 sec)

  7. Download
Query OK, 0 rows affected (0.00 sec)

  8. Tag
Query OK, 0 rows affected (0.01 sec)

  9. Conn
Query OK, 0 rows affected (0.02 sec)

 10. Keyword
Query OK, 0 rows affected (0.01 sec)

Tables Created - Committing Changes
Query OK, 0 rows affected (0.00 sec)

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

mysql> quit;
Bye
#

	Note
	this step is RECOMMENDED unless you know precisely what you are doing. Some commercial sites may not wish to preload this data, but should substitute their own alternatives if they want certain features to work.

	Warning
	If you changed the password in step 1. above from the default value, you NEED to have made the matching change to the configuration file before doing this step.

There are three database tables that contain standard values, plus whatever you add to them over time; these are called keywords, photographers and vendors. In this step you will be loading some initial values into these database tables. To do this you need to go to /usr/share/wacs/samples/database and run the three populate commands in the utils directory on the XML data files there.

# cd /usr/share/wacs/samples/database
# /usr/share/wacs/utils/keywordpop keywords.xml
Inserting Entry For Keyword: seethru
Inserting Entry For Keyword: nopanties
Inserting Entry For Keyword: teen
[...]
Inserting Entry For Keyword: cyc
Inserting Entry For Keyword: country
Inserting Entry For Keyword: alley
# /usr/share/wacs/utils/photpop photographers.xml
Inserting Entries For Photographer: DFR
Inserting Entries For Photographer: SWE
Inserting Entries For Photographer: MAX
[...]
Inserting Entries For Photographer: JAN
Inserting Entries For Photographer: TOB
Inserting Entries For Photographer: HBM
# /usr/share/wacs/utils/vendpop vendors.xml
Inserting Entries For Site: SE
Inserting Entries For Site: WACSD
Inserting Entries For Site: FJ
[...]
Inserting Entries For Site: AMK
Inserting Entries For Site: KPC
Inserting Entries For Site: KHA
#

	Note
	This is a very optional step but will help you if you're setting up a WACS web site for the first time.

This step loads three sample model records into the database to provide an example of how a typical model record might look. There are three such files provided in /usr/share/wacs/samples/models containing details of three models: Kaz B, Sabrina and Roxanne.

# cd /usr/share/wacs/samples/models
# wacsimport Sabrina-18.xml
Keyless ID map for JAFN
# wacsimport Roxanne-24.xml
# wacsimport KazB-30.xml

	Note
	For some sample sets for your new WACS web site, we invite you to visit our demonstration site at PinkMetallic.com - [CAUTION - contains adult material]. Access to this site is currently free but there may be a small charge at some point in the future if referal revenues don't cover costs.

You will first need to download the sets that appeal to you, so if you select set number 14 for instance, you will need the set14.zip file and the set14.xml file. These can be found via the link titled WACS Resources from the main menu on PinkMetallic.com. Once you have these downloaded, place them both in the same directory and run the wacsxmlin program to load the data from the XML file. The wacsxmlin program requires the name of the .xml file it is to read as an argument, eg wacsxmlin set4.xml. The zip file will be automatically unpacked and it's contents placed in the images area. In this example, we're going to use the default layout, which if you haven't edited the configuration file will be gallery style (please see the discussion on Site Layout in the administration guide for more details).

# cd ~/Download
# wacsxmlin --default set14.xml
Unpacking archive:
  Roxanne07001.jpg
  Roxanne07002.jpg
  Roxanne07003.jpg
[...]
#

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.

The easy bits are looked after by the upgrade command; to run this download and unpack the new distribution, and as the super user (root) run the following commands:

# cd unpack_location/install
# ./upgrade
WACS - Upgrade
--------------
[...]
Do you wish to continue? (y/n): y
[...]
# 

At the end of it's run, upgrade will print out some key notes about things that will require manual attention to get the new release working. The section below will give you some guidance on how these may be achieved.

The upgrade command will give you some information on what extra steps you may need to take to migrate to this release. For example, it may tell you that a new database field needs to be added to a particular model schema. In the transition from 0.5 to 0.6.x the mrace field was added, and upgrade will tell you about this. First step is to find the specification of the field from the appropriate SQL script in the creation directory, so for Oracle this will be creation/ora_models.sql. From this you will see that the field specification for Oracle is:

[...]
 mrace            varchar2(15),
[...]

You have three options for adding this to the database - you can choose to alter the existing schema (may leave fields in an odd order in describe); you can rename the existing table, create the new one, copy the data across and then repoint any relational constraints to the new table; or you can export your entire database, create a fresh one and import the records back in (the tools do not cover connections, saved searches or customised infra-structure tables (keywords, vendors, photographers) at present but are otherwise quite usuable). The former is quick and easy if the database supports it but leaves the field list in an odd order; the middle one is more work but produces a fully "normal" schema in the end but requires serious black magic if your database understands relational constraints. The final one is *VERY* experimental at this point but will improve with time.

Here is a worked example that shows how to use the alter table syntax in Oracle's SQL*Plus command interpreter to add one field called mrace:

% sqlplus
[...]
Username: wacs
Password: ****

sqlplus> alter table models
       > add ( mrace      varchar2(15) );

Table altered.
sqlplus> commit; 

Commit complete.
sqlplus> desc models
[...]
 MRACE                VARCHAR2(15)
sqlplus> quit
%

Another issue you need to be aware of is that the upgrade script will not over-write any existing files in the wacs web document tree (by default this is /var/www/html/wacs) because you may well have tailored them and we wouldn't want to overwrite those. You may well therefore need to look at what is in the htmlbones directory and copy some of the new files across into your web tree, or merge the new html into your modified version of the pages.

If the first group of actions that wacssetup takes seem to have gone OK, and then the next step where it creates the schema starts to show problems, then we need to check if anything got created. This particular step is where problems with the server IP address configuration often show themselves, particularly when using MySQL as it is the first time that we try to use our Wacs system credentials in earnest. Please see the section called “Preparation Tasks” for more information on this. A sure sign of this failure will be an error message something like this:

DBI connect('wacs:www.example.com','wacs',...) failed: Access denied for
 user 'wacs'@'myserver.example.com' (using password: YES) at wacssetup
 vendpop line xxx
Can't connect to database
Reason given was Access denied for user 'wacs'@'myserver.example.com'
 (using password: YES)

Verifying Schema

Anyway, if you're seeing this kind of message, you need to verify if the database schemas did indeed get created or not. To do this, we log into SQL with the Wacs user account details as follows (change account names and passwords as appropriate):

% mysql -u wacs -p wacs
Enter password:
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 316
Server version: 5.0.84 Source distribution

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

mysql> describe conn;
+-----------+--------------+------+-----+---------+-------+
| Field     | Type         | Null | Key | Default | Extra |
+-----------+--------------+------+-----+---------+-------+
| centryno  | int(9)       | NO   | PRI | NULL    |       | 
| cgroup    | int(6)       | YES  |     | NULL    |       | 
| corder    | int(3)       | YES  |     | NULL    |       | 
| cflag     | char(1)      | YES  |     | NULL    |       | 
| cstatus   | char(1)      | YES  |     | NULL    |       | 
| cmodelno  | int(6)       | YES  |     | NULL    |       | 
| csetno    | int(9)       | YES  |     | NULL    |       | 
| cphotog   | varchar(6)   | YES  |     | NULL    |       | 
| ctype     | varchar(20)  | NO   |     | NULL    |       | 
| cdesc     | varchar(80)  | YES  |     | NULL    |       | 
| ccomments | varchar(240) | YES  |     | NULL    |       | 
| cpath     | varchar(160) | YES  |     | NULL    |       | 
| cadded    | date         | YES  |     | NULL    |       | 
| camended  | date         | YES  |     | NULL    |       | 
+-----------+--------------+------+-----+---------+-------+
14 rows in set (0.00 sec)

mysql> quit
%

	Note
	The SQL commands used, describe and quit are identical for Oracle although the formatting and output will differ slightly.

If you instead get a message like: ERROR 1146 (42S02): Table 'wacs.conn' doesn't exist then that is confirmation that the schema create phase had failed. Once you've resolved the cause (most likely these hostname issues), you have two choices:

• remove the existing half built structures and run wacssetup again (see below)
• complete the database creation manually picking up the manual install instructions from the appropriate point.

% mysql -u root -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is xxx
Server version: 5.0.84 Source distribution

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

mysql> drop user 'wacs'@'localhost';
Query OK, 0 rows affected (0.01 sec)

mysql> drop user 'wacs'@'myserver';
Query OK, 0 rows affected (0.01 sec)

mysql> drop user 'wacs'@'myserver.example.com';
Query OK, 0 rows affected (0.01 sec)

mysql> drop database wacs;
Query OK, 10 rows affected (0.01 sec)

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

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

mysql> quit
Bye
%

Once you've got beyond the user account, database area and database schema creation steps, there is really only the initial data population left to be done. For this it's simplest to just follow the last steps of the the section called “Manual Database Creation Steps” process from the step the section called “3. Create default database contents (optional)”.

If the wacssetup completes normally but you fail to to login when you're sure you're using the right username and password, there's a couple of things to try. run /usr/bin/pam_auth (packaged installations) or /usr/local/bin/pam_auth (easyinstall/manual installations) - give it your username and password, separated by a space, and then press <ENTER>. If it replies with OK all is well; if it replies with ERR or some other error message (and you know you typed your password right of course) then there's a problem.

Most likely it's in /etc/pam.d and to do with the file called wacs there. Compare it to other files in the same directory like sshd and squid (if present) for the correct dialect for this platform. The security sub-directory of the Wacs source tarball contains various versions written over the years, one of which may be in the correct PAM dialect.

The next step is probably to follow the manual creation instructions at this point and see how they progress. If those fail, please visit our web sites - sourceforge site or launchpad site or use our mailing lists or email address to get help.

	Tip
	Do take a look through the checklist below the section called “General Troubleshooting Tips” as there may be tips there that help and at the very least having gone through these will help us get to the root cause of your problem quicker.

SELinux is an enhancement to Linux that allows potentially vulnerable services (like an internet-exposed web server) to be operated on a basis where each action the program tries to take needs to be explicitly allowed, rather than the normal allowed unless denied approach of most Unix environments. As such SELinux presents a whole new group of challenges for getting WACS to work, because we have to extend the ruleset as to what is allowed and what is not. It can be done, but it will take work and some experimentation. Whereever we have not used the Operating System supplied packages (Web Server, Database, etc), we're going to have to add those rules. The first thing to check is whether SELinux is enabled - to do this, type:

% sestatus
SELinux status:                 enabled
SELinuxfs mount:                /selinux
Current mode:                   permissive
Mode from config file:          permissive
Policy version:                 20
Policy from config file:        targeted
%

If it's either disabled, or is enabled but with a current mode of permissive, it's not actualling going to be causing us a problem right now. If it is enabled and enforcing, we've got to work on it. The web server process needs a security context of httpd_sys_content_t to be present on any directory it needs to access, so the first step is to add this context to each directory (outside of the normal ones) that it is likely to access. This is done with the chcon commands shown above in the manual install chapter - example:

# chcon system_u:object_r:httpd_sys_content_t /var/run/wacs
#

In addition to the directory gaining the httpd_sys_content_t security context, any pre-existing files will also need the same, so this can be done with:

# chcon -R system_u:object_r:httpd_sys_content_t /var/run/wacs/*
#

To inspect the security context of a file or directory, you use the -Z option to the ls command:

# ls -Z /var/run/wacs/
-rw-r--r--  apache apache system_u:object_r:httpd_var_run_t leases.acl
#

While the easyinstall script does try to set these for all the areas the web server might go (/var/run/wacs, /etc/wacs.d and the files area /home/wacs/*), any problems which are causing avc_denied messages in the dmesg output are most likely down to this issue.

The first step to getting WACS to work with Oracle is to download a suitable set of client side applications and libraries - these are typically provided by Oracle 11i Instant Client or a package of a similar name. Generally doing a full install of instant client will provide all the libraries you need. The next step is to establish the necessary ORACLE_HOME environment variables and check that the Oracle stack is running by connecting to the server using the sqlplus client provided as part of the instant client package.

It should then be a fairly simple matter of using cpan DBD::Oracle to download, compile and install the necessary database driver for Perl DBI. Once that's done, you just need to follow the installation instructions for Oracle in the appropriate chapters of this guide.

The conventional install of Php5's pear DB routines actually does include the first line of support for Oracle in the form of the oci8.php file in /usr/share/pear/DB but this itself needs oci8.so which normally lives in /usr/lib64/php/modules. To make this module, you will need the full set of SQL*Net libraries as provided by either a full database installation or Oracle's instant client product. You will also need the C compiler and the php-devel package (this contains the command phpize so if trying to invoke phpize gives Command not found you almost certainly don't have the necessary development package installed.

Since WACS currently uses the now-obsolete Pear DB module for database access, it appears to be a bit of a challenge to find the correct source code. While we were preparing this document (May 2009), the source code for the OCI8 driver could be found at the PECL web site. If you down load this with something like wget and save it locally, running the following (assuming you have ORACLE_HOME set correctly) as root produced a successful install: pecl install oci8. All that then remains to be done is to configure the phpdbconnect string in the main wacs configuration file with the correct database specification and things should start to work.