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 or DEB packages of the WACS environment and are using the default applications (MySQL for the standard packages, PostgreSQL for the wacs-for-psql packages), the prerequisite applications will be automatically installed if they are not already present. If not, or you are using a different database (Oracle for instance), you will need to install these applications first as detailed in the table below and then follow the manual install steps:

	Tip
	This is the prefered way to install WACS. It is currently available for Fedora 27 or 29 based systems using the RPM package manager and for Ubuntu 16.04 LTS and 18.04 LTS systems using the DEB packaging system. It is our hope to extend the packaged software approach to include other platforms in a future release, CentOS 8.x being our next anticipated platform to be added.

	Note
	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
	We attempt to support the current and previous releases of both Fedora and Ubuntu when we make each new WACS release. Packaged support for previous releases is then dropped.

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 (dnf, gdebi 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, dpkg 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 rpm 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.

Note

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. We are gradually migrating to the layout preferred by the packaging and it shouldn't cause problems, but you do need to be aware of it, particularly if moving a configuration file between releases.

	Warning
	It is our intention to discontinue support for the easyinstall script in a release in the near future. You are strongly encouraged to use the other two methods, package install or manual install in preference.

The easyinstall script was our pre-packaging approach to installing WACS and we would advise against using it on Fedora and Ubuntu distributions, although it might prove useful for installing on older versions of Linux that are not supported directly by the packages we create. If attempting an install on RHEL or CentOS, try the Fedora packages first. For Debian, try the Ubuntu pacakages. As of WACS 1.0.0, the packages are quite mature and should be the best option. The easyinstall command may or may not still work. Additionally installations done with the easyinstall will prove harder to upgrade than those done with the packaged solutions.

All versions of WACS include the wacssetup configuration tool to provide an easy web-based setup interface replacing what easyinstall used to do.

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 32 (labeled fc32), and Fedora 34 (labeled fc34) and DEB packaged versions for Ubuntu 20.04 LTS and 21.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 1.0.1 on an x86_64 machine running Fedora 32), you will probably want the following packages substituting wacs-for-psql instead of the main wacs if you intend to use PostgreSQL as your backend database instead of MySQL:

If you also wish to make use of the Wacs-PHP API, The AJAX enabled dynamic search tools, 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 still supported), you will also want to get the package called wacs-download-1.0.0-1.noarch.fc29.rpm. You may also wish to download one of the two versions of the documentation package: wacs-doc-pdf-1.0.0-1.noarch.fc29.rpm or wacs-doc-html-1.0.0-1.noarch.fc29.rpm - you can always access the same documentation direct from our sourceforge web site.

	Note
	The packages wacs, wacs-for-mariadb and wacs-for-psql are mutually exclusive - pick which one you want and download ONLY that version. They contain the same files and just have differences in the other packages they depend on and how the postinstall script that is part of them acts.

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:

# dnf install 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 Database Server are enabled and running. These should be respectively mysqld for MySQL, mariadb or mysqld for MariaDB and postgresql for PostgreSQL. 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 (named apache2 on Ubuntu) and mysqld (etc) if these are not shown as currently running. If you prefer using the command line, the following steps will do the same task:

# systemctl start httpd
Enter SSL pass phrase for nemisis.example.com:443 (RSA) : ********
# systemctl start mariadb
# systemctl enable httpd
# systemctl enable mariadb
Created symlink from /etc/systemd/system/multi-user.target.wants/mariadb.service to /usr/lib/systemd/system/mariadb.service.
# 

On older systems (no longer supported by the packaged versions), you may need to use the following commands:

# /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. 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 16.04 LTS and 18.04 LTS, while RPM packaged versions are available for Fedora 27 and 29. 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 1.0.0 on an x86_64 machine running Ubuntu 18.04 LTS) you will probably want the following packages remembering to choose whether you want the wacs-for-psql package for PostgreSQL database support instead of the default MySQL for the wacs:

If you also wish to make use of the Wacs-PHP API, The AJAX enabled dynamic search tools, 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 still supported), you will also want to get the package called wacs-download_1.0.1-1.all.deb. You may also wish to download one of the two versions of the documentation package: wacs-doc-pdf_1.0.1-1.all.deb or wacs-doc-html_1.0.1-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 do the package installations. There are any number of ways to do this, and you can pretty much use any of them; we recommend use of the gdebi package manager which is an optional package that you will almost certainly have to install first. This can be achieved using a number of the standard Ubuntu tools including apt-get install, aptitude or by using the Ubuntu Software Center. We have not used the Ubuntu software center, aptitude or synaptic package manager in these instructions because those only really cope with software provided by the main Debian repositories. The gdebi mixes it up allowing the installation of a locally downloaded DEB file, combining it any packages it depends on through the normal package repositories mechanism. Unfortunately sourceforge.net does not, as we are writing this manual, support the creation of debian style package repositories.

	Note
	Additionally it is usual for GDebi to be configured as an action listed on the actions (right click) menu in the GNOME file manager as installed on Ubuntu for debian packages. You can use this method instead if you prefer.

Once you have installed gdebi, the easiest way to start it up is to click on the Meta (Windows) button and search for it as shown below. Using the file manager to browse to your downloaded files, and then right clicking on the files works too. We're going to show you the pure gdebi way so double click on the icon to start it running:

Once gdebi is running you use the File menu Open option to open each DEB package file in turn. 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 (or wacs-for-psql ) 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_1.0.1-1_all.deb . We choose File -> Open in gdebi as highlighted in green below:

At this point the Open File browser will appear and offer you a number of the most common locations to find the files you are looking for. In the illustration below, we're looking in the top option Desktop for the files as we can see them on the desktop behind the Open File Dialog box of gdebi. Other likely locations are the Downloads directory or your home directory. The screenshot below shows this step:

The next step is to select the first of the packages for installation - this should always be wacs-core as this contains the basic bones of the WACS installation that are needed in all cases. The screenshot below shows this being selected in gdebi:

Clicking on the Open button will cause a summary screen to appear, detailing the basic information about the package you are about to install. This is shown below - a key item to look out for in this screen is the bit where it says Status: - sometimes this will say as it does in this screen that All dependencies are satisfied but on some occasions it will say how many additional packages need to be installed. This can be a quite large, sometimes as high as twenty or thirty packages:

While this 28 packages figure may sound high, it's what is actually needed in terms of software infrastructure (libraries and helpers) 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 php7 programming language, and a range of special libraries and tools that we use when accessing media files like photos and videos. These will also include all the various Perl and PHP modules we use for database access and the like.

We click on the Install Package button and an additional dialog box may appear requiring Authenication as illustrated below:

Initially a 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 8/MariaDB 10/PostgreSQL 10, apache 2, Php 7 and the perl modules required.

However under some circumstances you may notice that it doesn't show any progress through this process. Although this was mainly a problem with earlier releases, it can still happen. Sometimes the cause is issues with your internet connection or the configuration of your package manager, it can also be that an older package is requesting some user intervention. You can click on the down arrow by the progress bar to expand the Terminal window and see the actual problem. Once you have attended to this, the install process should continue normally.

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:

You now need to repeat the same steps for the other packages; we would suggest installing wacs-hostauth next unless you are only planning to use the internal database for user authentication. Even then it can be useful to have the wacs-hostauth package installed for initial setup and testing. Unless you are doing all the media ingest operations on a separate workstation with connections to the database and the storage, you will also need wacs-tools. You almost certainly also want the documentation set in one form or another so choose one of wacs-doc-pdf or wacs-doc-html; both is fine too - they don't actually take up that much space. We would also suggest that you do install the wacs-samples package as well as several of the samples (attrib.xml and keywords.xml) are pretty much essential to getting the initial system up and running. You can choose not to install our sample models and vendors at the setup stage if you don't want those.

When we get to the wacs package itself, we use one of three possible options: the MySQL 8 version (default), the MariaDB 10 version or the wacs-for-psql for PostgreSQL support. There is no difference in the actual version of WACS provided, just in the configuration files and actions it takes for the respective database types. If you intend to use a different database like Oracle 12, you can select either of the wacs packages - the code is the same.

The main wacs package comes 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.

Once they're all done, you should be ready to proceed to the next step. We have worked hard to get the packages to do as much of the initial setup as we can and you should at this stage be able to simply move on to running the wacssetup which we will cover in the next chapter Chapter 6, Creating The Initial WACS Databases.

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_username with your user name:

# usermod -a -G wacs your_username
#

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

# sudo usermod -a -G wacs your_username
[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. Here you can choose which Database you plan to use: MySQL/MariaDB, Oracle 10+ or PostgreSQL 9.6+ as shown below:

Once you have selected the Database type, you need to select the name of the database system administrator to use - we don't automatically select the one normally for the specific database as it is very possible to use the other names on different databases. If you are running on a large Oracle system for instance, your DBA might choose to create you an admin account for just your database activities - wacsdba as used in PostgreSQL would be a good name for them to use. You might even want to suggest they use that!

Important

The wacs-for-psql version works a little differently from other versions - the postgres DBA is not by default accessible to webapps and to this end we create an additional DBA account called wacsdba as part of the installation process. By default this has the password Wacs4P0rn which you should change as soon as possible after the installation has completed. See the section later in this chapter about this.

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 13, 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 13, 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)

 11. Wacsuser
Query OK, 0 rows affected (0.01 sec)

 12. Attrib
Query OK, 0 rows affected (0.02 sec)

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

	Tip
	The wacspop replaced the previous seperate commands in Wacs release 0.8.6. If you're using an earlier release these instructions will not work. Check the earlier version of this document instead!

There are four database tables that contain standard values, plus whatever you add to them over time; these are called keywords, photographers, attrib 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 wacspop populate command in the utils directory on each of the XML data files there in turn. There is also the users.xml file which you should propably also load - you will need it if using the database as the authentication source. This is typically necessary for WebHosted sites and extremely useful on any pay sites.

# cd /usr/share/wacs/samples/database
# /usr/share/wacs/utils/wacspop 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/wacspop 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/wacspop 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
# /usr/share/wacs/utils/wacspop attrib.xml
Inserting Entries For Attribute: shaven
Inserting Entries For Attribute: tinytit
Inserting Entries For Attribute: nopanties
[...]
# 

	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
[...]
#

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 includes support for authenticating using user account information stored in the main WACS database. Either this or wide open access are the normal ways of operating in a Web Hosting environment. The user account database includes lots of fields useful in managing subscriptions via this method. Bevtec Communications Limited are working on a customer management extension using these fields, please contact them for more details. Alternatively you can develop your own utilising the hooks we have put there for this purpose. You can visit our demostration site, PinkMetallic.com to see the open access system in operation.

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.

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> 

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

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.

The first details for how to setup WACS for use in a Web Hosting Provider's environment were introduced in 0.8.4 and are based on our own experience setting up PinkMetallic.com at justhost.com. We've since set WACS up for a consultancy client on godaddy.com - you need to use Wacs 0.9.1 or higher for it to work on godaddy because of the need to use .pl extensions for the command names. Please note this is not a specific endorsement of these two providers; merely a point of reference on what has been successfully achieved in the past.

	Warning
	Facilities and configurations do differ between web hosting providers and there is no guarantee that any specific provider's offering is suitable for running WACS. We do try to help were we can, and www.bevteccom.co.uk do offer WACS installation consultancy services. 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 modicons images wacs
#

Another issue, with one web hosting provider we worked on, we found that the wacspop command wouldn't work due their using MySQL 5.0 and an earlier version of the interface routine. This problem manifested itself in an error from the column_info - changing the empty string specifiction from '' to a wildcard '%' in the final parameter worked around this problem.

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. We might also see i686 if the hosting company are using 32-bit Intel architecture servers. You can also try the following for more details if it looks like it might be either a redhat-based (CentOS,RHEL,Oracle Unbreakable,etc) or debian-based (Ubuntu,Debian,etc) Linux distribution they're using:

# cat /etc/redhat-release
CentOS release 5.5 (Final)
# cat /etc/debian_version
cat: /etc/debian_version: No such file or directory
#

For CentOS or RHEL, 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. These can usual be found starting at the release number, say 5.5 , then choosing os then choosing the architecture either x86_64 or i386 (an alias for i686) as appropriate. The package files themselves are then usual found in the CentOS directory. 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.

	Tip
	If the webhosting company is using an older version of CentOS and you can't find the appropriate binaries on the mirror site, try vault.centos.org

# 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 wacsgenimg) 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, ppmtogif, 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. If you're using our sample WebHosting configuration file as a basis, we may have already set this one up for you. You will also need to add a suitable entry in your .bashrc or .cshrc to set LD_LIBRARY_PATH for your shell.

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.

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

If the majority of your video content is in .mp4 aka MPEG-4 format using either the original MPEG-4 codec or the improved H.264 standard, it is possible to enable a streaming mode in the Apache webserver. If you do this people will be able to play the video directly in their web browsers and be able to jump around in the timeline to skip segments, or repeat them. This is not a built-in feature but one that can quite easily be added using a plug-in module for Apache called mod_h264_streaming .

HOWEVER there are constraints as this software is not free although the source code is fully available. The software is free to use on non-commerical sites but requests attribution with a statement like This website uses H264 pseudo video streaming technology by CodeShop be added to the site. If you are using the web server commercially, you need to acquire a license at http://h264.code-shop.com/trac/wiki/Mod-H264-Streaming-License-Version2 - the license is inexpensive - 35 Euro/Approx $42 - so it shouldn't be a huge issue and well worth it for the improvement in user experience.

For Fedora/CentOS systems, the mod_h264_streaming driver has been packaged by the RPM Fusion project rpmfusion.org and is called mod_h264_streaming-2.2.7-6.el7.x86_64.rpm. If you follow the instructions on rpmfusion.org to enable the correct Non Free repository on your particular distribution, it should simply install with dnf install mod_h264_streaming.

We have not been able to find a reliable source for a similar package on Ubuntu/Debian systems, so we would recommend following the pretty clear instructions given on the author's site at: http://h264.code-shop.com/trac/wiki/Mod-H264-Streaming-License-Version2

	Note
	You may notice that the website hasn't been updated in a lot of years but it all still seems to work and there doesn't seem to be any other major alternative other than perhaps the Apache Traffic Server project - trafficserver.apache.org but that is a massive package covering a multitude of proxy cache functionality of which MP4 streaming is only a tiny part.

The H264 streaming driver consists of just three files - two live in the apache 2 configuration directory (/etc/httpd on Fedora/CentOS/RHEL, /etc/apache2 on Ubuntu/Debian) and a third (mod_h264_streaming.so) in with the other apache modules in /usr/lib64/httpd/modules. The two configuration files are conf.d/h264_streaming.conf and conf.modules.d/10-h264_streaming.conf. The first one h264_streaming.conf simply tells Apache to pass .mp4 files to the h264-streaming module for extra processing:

AddHandler h264-streaming.extensions .mp4

The second one 10-h264_streaming.conf simply tells apache to install the module as it starts up:

LoadModule h264_streaming_module modules/mod_h264_streaming.so

In summary, the vast majority of WACS sites will be significantly improved by adding this module and it is our strong recommendation that you do so if hosting mp4/H264 video files.

WACS should work just fine with mod_perl and it should significantly improve the performance of your website if you choose to use it. What it does is to execute the perl language that WACS is written in INSIDE the webserver itself rather than starting up the perl interpreter /usr/bin/perl each time.

More details will be added soon by essentially running the command a2enmod mod_perl should activate it. Once activated every thing should operate normally, only faster; the only caveat is that you will probably need to restart (as opposed to just reload) the webserver if you install any updated wacs programs while the webserver is runing.

While it is obviously vital to be able to upgrade an existing WACS installation from one release to another, there are a great number of factors that come into play. It is not always easy to resolve these and with WACS we've taken a modular approach to handling the issues presented. This means that we've provided tools for the necessary changes as separate entities and then integrated them together with the existing wacssetup web application to provide a wide palette of options. You can choose to let wacssetup walk you through the whole upgrade process, or you can choose to use each tool individually to customise the process to your needs.

The key things that need to be considered are:

We will discuss each of the tasks and the tools available to help with it individually before then walking you through letting wacssetup preform the entire process for you.

The new wacsschema compares the structure of the database to which it is currently talking with the files in the creation directory distributed with the latest version of the application code. If these differ, it provides a mechanism to update the existing database schemas to the new structure or to create new schemas where they are not present it the current database. This application is very unusual in that it has both a command line and web mode of operation, both of which function essentially in the same way. In general, it will ignore local customisations and leave them untouched during the upgrade process.

	Warning
	Changing the database structure is by it's very essence a tricky process and you should make absolutely sure you have good backups before attempting it. Seriously, please don't ignore this warning!

The first page shown to you by the wacsschema is a simple summary of the current state and takes no actions, so it's not fundamentally dangerous to invoke it. Just don't click on the Make These Changes button unless you're very sure and have backups! Shown below is typical of what it says if run on an upgraded installation that still has a pre-Wacs 0.8.5 database schema:

As you will see from this, it has determined that there are missing fields from the sets, models and keyword database schemas; that user, attrib and notes schemas are missing entirely. All the other database schemas are found to be complete and up to date. In the web version, it gives you the option to click on the Make These Changes button and it will run the appropriate SQL (we HOPE) to alter and/or create the database schemas as necessary.

	Note
	wacsschema does not remove any fields it does not recognise, so existing additional custom database fields will be left intact. Additionally it uses the SQL scripts relevant to the SQL Database type being used (ie MySQL5, Oracle, etc) from the creation directory within the wacs installation. Were you to add extra fields into those files, wacsschema would attempt to add them for you.

For those of you who either prefer command line applications or who are using a web hosting service where wacssetup doesn't work, wacsschema will automatically work in text-only mode if it doesn't detect that it's been run by a web server. Shown below is what it says when run in text mode:

% wacsschema
Schema photographer is unchanged.
Schema vendor is unchanged.
Schema sets is missing fields saltmedia, sfocus, sfps, sinter, snext, 
sprev, srank, ssetpos, sskipfr.
Schema models is missing fields magency, maltimage, mbirthdate, mbody
image, mdress, mlabia, monfile, mstarsign.
Schema assoc is unchanged.
Schema idmap is unchanged.
Schema download is unchanged.
Schema tag is unchanged.
Schema conn is unchanged.
Schema keyword is missing fields kiwear, kiwscore.
Schema user is not present in current database.
Schema attrib is not present in current database.
Schema notes is not present in current database.
%

As you will see wacsschema returns to the command prompt after delivering it's verdict on the database schema. If you want the Text Mode version to actually make the changes, you need to run wacsschema with the -y option. Thus to actually perform the schema update, you would use:

% wacsschema -y
[...]
%

The application code and related icons and other HTML bits are looked after by the upgrade command; to run this download and unpack the new distribution source code tree, and as the super user (root) run the following commands. Please make sure it is using the correct wacs.cfg file by setting WACS_CONFIG in the environment if necessary:

# cd unpack_location/install
# ./upgrade
WACS - Upgrade
--------------

Welcome to the WACS Upgrade script.  This script will
attempt to upgrade an existing WACS installation to the
latest version.  It does not attempt any of the initial
package installation steps, so if you've not installed
WACS before, you should be using easyinstall instead.

It will ask for confirmation before modifying any configuration
files (but as always you should have backups before upgrading
anything.

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. If you've used the wacsschema command to update your schema, you don't need to worry about these.

If not, you will have to make the schema changes that are needed by hand using your database's SQL command line tools. 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.

Obviously over time the defaults data we provide for the key database tables does get added to, improved and bug fixed. How you choose to handle this very much depends on how much you've customised your keywords, vendor and photographer data relative to the distributed versions. At the simplest level, it might be nice to simply reload everything but of course if your database enforces referential integrity as it should, you can't just drop an entire data set that has relations pointing to it. The current compromise is that the wacs data importer, wacspop will only create new entries that are not currently in the existing database. Any entry that is already there will remain unchanged, quite possibly not benefiting as it should from an update.

Before attempting anything as fundamental as altering the database schema, it's vitally important to back up the database first. So before we actually run wacssetup to do the upgrade, we'll take a dump of the database to disc just in case.

Backing Up A MySQL5 Database

For MySQL5 the simplest way of taking a suitable database dump is to use the mysqldump supplied as part of MySQL. Typical usage is as follows:

	Tip
	Do make sure that you've got space to store the resulting database dump file in the current directory. mysqldump can be run in any directory. You might want to make a special directory to store such dumps in.

% mysqldump -u wacs -p wacs > wacs-db-dump.mysql
Enter password:
%

The parameters are -u followed by the username you use to access the wacs database. If you've forgotten what this is, the dbuser value in the /etc/wacs.d/wacs.cfg is the one you want for this. The next parameter is -p which tells it to prompt you for a password. The final parameter is the name of the wacs database; again this can be confirmed from the dbname value in the wacs config file. The greater-than (>) sends the output into the file we've named wacs-db-dump.mysql (you might want to include the date in the name). The mysqldump program will then prompt for a password and silently perform the dump unless there's a problem.

It's also a good idea to check the file has been created. If you run the linux head command on the resulting database dump, it should look something like this:

% head wacs-db-dump.mysql
-- MySQL dump 10.13  Distrib 5.1.56, for redhat-linux-gnu (x86_64)
--
-- Host: localhost    Database: wacs
-- ------------------------------------------------------
-- Server version	5.1.56

/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */;
/*!40101 SET @OLD_CHARACTER_SET_RESULTS=@@CHARACTER_SET_RESULTS */;
/*!40101 SET @OLD_COLLATION_CONNECTION=@@COLLATION_CONNECTION */;
/*!40101 SET NAMES utf8 */;
/*!40103 SET @OLD_TIME_ZONE=@@TIME_ZONE */;
[...]
% 

% exp

Export: Release 11.1.0.6.0 - Production on Sun Jul 31 07:50:46 2011

Copyright (c) 1982, 2007, Oracle.  All rights reserved.


Username: wacs
Password:

Connected to: Oracle Database 11g Enterprise Edition Release 11.1.0.6.0 - 64bit Production
With the Partitioning, OLAP, Data Mining and Real Application Testing options
Enter array fetch buffer size: 4096 >

Export file: expdat.dmp > wacs-dump-31Jul11.dmp

(1)E(ntire database), (2)U(sers), or (3)T(ables): (2)U >

Export grants (yes/no): yes >

Export table data (yes/no): yes > 

Compress extents (yes/no): yes > 

Export done in US7ASCII character set and AL16UTF16 NCHAR character set
server uses WE8MSWIN1252 character set (possible charset conversion)

About to export specified users ...
User to be exported: (RETURN to quit) > wacs

User to be exported: (RETURN to quit) >

. exporting pre-schema procedural objects and actions
. exporting foreign function library names for user WACS 
. exporting PUBLIC type synonyms
. exporting private type synonyms
. exporting object type definitions for user WACS 
About to export WACS's objects ...
. exporting database links
. exporting sequence numbers
. exporting cluster definitions
. about to export WACS's tables via Conventional Path ...
. . exporting table                          ASSOC      36065 rows exported
EXP-00091: Exporting questionable statistics.
. . exporting table                           CONN        429 rows exported
EXP-00091: Exporting questionable statistics.
. . exporting table                       DOWNLOAD      44141 rows exported
EXP-00091: Exporting questionable statistics.
. . exporting table                          IDMAP       4457 rows exported
EXP-00091: Exporting questionable statistics.
. . exporting table                        KEYWORD        171 rows exported
EXP-00091: Exporting questionable statistics.
. . exporting table                         MODELS       3402 rows exported
EXP-00091: Exporting questionable statistics.
. . exporting table                   PHOTOGRAPHER         75 rows exported
EXP-00091: Exporting questionable statistics.
. . exporting table                           SETS      33882 rows exported
EXP-00091: Exporting questionable statistics.
. . exporting table                            TAG       1026 rows exported
EXP-00091: Exporting questionable statistics.
. . exporting table                         VENDOR         15 rows exported
EXP-00091: Exporting questionable statistics.
. exporting synonyms
. exporting views
. exporting stored procedures
. exporting operators
. exporting referential integrity constraints
. exporting triggers
. exporting indextypes
. exporting bitmap, functional and extensible indexes
. exporting posttables actions
. exporting materialized views
. exporting snapshot logs
. exporting job queues
. exporting refresh groups and children
. exporting dimensions
. exporting post-schema procedural objects and actions
. exporting statistics
Export terminated successfully with warnings.
% 

The WACS distribution currently comes with four XML files containing default values for some of the main database tables. These are:

In WACS release 0.8.6 the code that previously read the defaults XML files for each database table was merged into a new single data population utility called wacspop. This replaced the previous separate populator commands: vendpop, keywordpop and photpop and obviated the need for the creation of a new command for handling the new attributes schema. With this move, it became necessary for each XML file to better identify what it actually was. It was therefore decided to add three extra attributes into each file, very similar to those already used by the data exchange XML files created by wacsexport, wacsxmlout and wacsselout.

Three new attributes were added to the database population XML files:

If you wish to convert an older file to the new format so that it can be imported by wacspop, you merely need to add these three values near the top (typically third line) of your XML file using a normal text editor.

 [...]
 <version>WACS_POPULATE_VERSION_2</version>
 <coreschema>vendor</coreschema>
 <revisiondate>29-MAY-2011<revisiondate>
 [...]

Once this has been done, wacspop should import your XML file taken from a previous release of Wacs. Do be aware however that moving an older file to a newer release will not populate the new fields added for Wacs 1.0.0 and these fields will remain empty. It is an intended future upgrade for wacspop that it should be able to update records as well as just add any that are not currently there.

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 Instant Client or a package of a similar name. Of course this does not include the database itself but when using the likes of Oracle, it would be quite normal (but not required) to have separate web servers and database engines. Wacs works just fine on multiple front end web servers with a single Oracle backend. Similarly collection administration and straightforward use can be performed on a separate workstation from hosting the database.

Generally doing a full install of instant client will provide all the libraries you need. If you are downloading these from the Oracle OTN web site, you will need the following packages either as zip files or rpms if that is the package manager on the distribution you are using.

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 (sometimes called sqlplus64 on the older x86_64 versions) provided as part of the instant client package. If this reports that the necessary shared libraries are not found, this may be because the dynamic library caching configuration files have not been created as needed. For RedHat based distros like Fedora, this is achieved by creating a file in /etc/ld.so.conf.d/ called something like oracle-19-installclient.conf which simply contains a single line pointing to where the files like libsqlplus.so are to be found. For the x86_64 version of instantclient installed from the RPMs, this should be /usr/lib/oracle/19.6/client64/lib assuming the RPM was installed into it's default locations. Once this file has been created, you just need to run ldconfig as root to rebuild the /etc/ld.so.cache to include the files in this path.

If you get the message sqlplus64: error while loading shared libraries: libnnz11.so: cannot enable executable stack as shared object requires: Permission denied that means that SELinux is still active on your host and has barred access to the Oracle libraries. The quick fix is to disable SELinux by running setenforce permissive as root on your machine and editing the file /etc/selinux/config to set the mode to permissive on subsequent system boots.

Once you've actually got the sqlplus program to run, that is unfortunately not usually the end of the story as it has to be configured to find the database server, etc. There are two parts to this task - firstly to create a suitable tnsnames.ora file to describe how to contact your server - place this into a newly-made /etc directory within the oracle instant client directory. Secondly you need to set environment variables that tell instant client what to look up within that tnsnames.ora file. This is done by establishing four environment variables, ideally globally for the system - these are:

In many ways the best way to establish these environment variables is to create the appropriate files in the global profiles directory, which is to be found in /etc/profile.d. Typically it's best to create two files called something like oracle11g-instantclient.sh with commands for sh/bash shells, and oracle19-instantclient.csh with commands for csh/tcsh shells. The shell (.sh) file should look something like this:

export ORACLE_HOME=/usr/lib/oracle/19.6/client64
export ORACLE_SID=yourdbname
export TWO_TASK=yourdbname
export TNS_ADMIN=/usr/lib/oracle/19.6/client64/etc

You may also wish to alias sqlplus64 to sqlplus if you're using one of the old versions of the instant client that used this name.

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. We do also support using the PDO interface as from Wacs 1.0.0. We have not yet re-written the WACS sample programs to use PDO but may well do in due course.

While we were preparing this document (March 2011, revised May 2018 and June 2020), 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. You then need to enable the extension in php itself; in some distros this is done by simply adding extension=oci8 into the /etc/php.ini file, while in more recent distros it is now convention to create a file called oci8.ini in the directory /etc/php.d containing this line. Once this configuration change has been made, you will need to restart your web server to make the new settings live. 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.

Building support for the PDO - PHP Data Objects - module is rather more complex unfortunately. The good news is that it is a fully integrated part of PHP itself and it's source code is part of the main PHP sources. The bad news is that many Linux distributions turn it off when they are building php (as being proprietory code); others are at least building the hooks and putting it in a package. If you can't find a suitable package, you may well be able to build one quite easily.

Here are the steps to take to do this - you may need to install the necessary packages for building packages such as php-devel (Fedora, RedHat, CentOS) or php7.3-dev (Debian, Ubuntu).:

RPM-based distros:
% cd rpmbuild/SRPMS
% dnf download --source php
% rpm -iv php-7.4.6-1.fc32.src.rpm
% cd ../SOURCES
% tar -xJf php-7.4.6.tar.xz
% cd php-7.4.6/ext/pdo_oci
% mkdir -p ~/src/php/pdo_oci
% cp -r * ~/src/php/pdo_oci
% cd ~/src/php/pdo_oci
% phpize
% ./configure --with-pdo-oci=shared,instantclient,\
/usr/lib/oracle/1.9.6/client64/lib,19.6.0.0.0
% make
% sudo make install
%
DEB-based distros:
% cd debuild
% aptitude source php7.3
% cd php7.3-7.3.11/ext/pdo_oci
% mkdir -p ~/src/php/pdo_oci
% cp -r * ~/src/php/pdo_oci
% cd ~/src/php/pdo_oci
% phpize
% ./configure --with-pdo-oci=shared,instantclient,\
/usr/lib/oracle/1.9.6/client64/lib,19.6.0.0.0
% make
% sudo make install
%

This alternative solution is essentially to download the source packages for PHP for your distribution and rebuild the piece of them that we need by enabling the --with-pdo-oci flag. If you are using the Oracle Instant Client distribution, you specify this with --with-pdo-oci=instantclient,/usr,19.6.0.0.0 as an option to the configure script where the /usr is where it is installed and 19.6.0.0.0 is the exact Oracle DB version number. Do remember that the php version will be updated from time to time and you may need to update the driver to match the current version.

	Note
	For PHP7 or PHP8, you will need a minimum of oci8-2.1.8 which should be available from pecl as before. See the sectiona above for details of how to install it.

Some distributions have now moved over to using php-fpm to provide PHP functionality from within the Web Server. Generally this is a good idea as it stops the web server having to start up a new PHP interpreter each time. Unfortunately it stops the method we've used previously and in other languages to set the essential ORACLE_HOME environment variable needed for the oci8 and PDO oci drivers to work. These instead now have to be set in /etc/php-fpm.d/www.conf where you have to add a line of the form env[ORACLE_HOME] = /usr/lib/oracle/19.6/client64 to it. Of course you need to change the path to the actual install location of your Oracle database software. Once added you need to do a systemctl restart php-fpm.service to make your changes active.

PostgreSQL is rather different from Oracle and MySQL as it tends towards using the host operating system authentication mechanisms for identifying users rather than a more conventional username and password combination. It can be reconfigured to allow username and password login, and we attempt to do this in as minimalist a way as possible to preserve normal operation for other users of the database. By default, the system manager account, postgres gains automatic database manager authority when it invokes any of the postgres tools (like the SQL command line, psql).

Warning

NB: some Linux distributions, eg Ubuntu, support simultaneous installation of multiple versions of Postgresql. In this case, you may find that the TCP/IP port number on which the database listens has changed from the default of 5432. In one case on an Ubuntu Xenial system which had been upgraded from previous releases; PostgreSQL 9.1 had port 5432, PostgreSQL 9.3 had port 5433 and PostgreSQL 9.5 had 5434. All of these were configured in /etc/postgres/<release_no>/main/postgresql.conf so do check the port = directive to make sure you are connecting to the version of the database you think you are.

With more recent versions of PostgreSQL configuration has been relocated into /var/lib/pgsql and the key configuration files like pg_hba.conf and pg_ident.conf held in the data sub-directory of /var/lib/pgsql. The wacssetup and package post install scripts make the necessary changes to these files but we've seen issues with the postmaster process not restarting properly once the changes Wacs needed have been made. You may also have to edit the postgresql.conf file in /var/lib/pgsql/data to include pg_hba.conf and pg_ident.conf to make these new settings active. A reboot or restart of postmaster should rectify things once these changes are in place. We will try to improve the handling of these install activities in the next release, but the version in Wacs 1.0.1 does the correct edits to the config files for you.

A key point to understand is that the Perl DBD driver and similar interfaces to PostgreSQL use the network domain rather than the named pipe for communication and this is not by default enabled by the installation packages for PostgreSQL. In the next section, we will take you through the setup and configuration steps needed for PostgreSQL to interact with the network properly.

There are three steps you need to take to enable network-based operation in postgres; to do these as described belowe you will need access to either the postgres or root accounts for the server computer. If you do not have access to this, there may be other ways to do what is needed via cPanel or similar but you will have to consult a suitable administrator for the system you are using.

Here we give a few tips and tricks on using PostgreSQL which may not be immediately aparrent.

SET search_path = wacs,public;
BEGIN;

SET client_encoding to 'UTF8';
SET sychronous_commit TO off;
SET CONSTRAINTS TO DEFERRED;
SET search_path = wacs,public;

COPY sets(setno,stype,sstatus,sauto,....) FROM STDIN;
2	I	A	N,....
7	I	A	N,....
\.

COMMIT;