NOTE: These instructions refer to the old Pawtucket interface, which is no longer supported. Installation instructions for its successor, Pawtucket2, are available
What is Pawtucket?
Pawtucket is general purpose public-access publishing tool for CollectiveAccess. It provides an easy way to create web sites around data entered into CollectiveAccess using the Providence cataloguing tool. Pawtucket provides many features for displaying, finding and interacting with collections information, including:
- Full text search with auto-suggestion functionality
- Configurable faceted browse
- Ability to browse within search results (aka. "refine your search")
- Configurable detail displays for collection objects and all authorities- you can show as much or as little information from your database as you want
- Support for "features" - simple online exhibitions using curator-defined sets. System is extensible so you can define your own feature-types.
- Support for user-created tags, comments, ratings and object slideshows
- Not object-centric. While objects are usually the focus of a collections front-end, with Pawtucket they don't have to be. You can search and browse in any authority in addition to collection objects. This lets Pawtucket work in specialized applications such as biographical catalogues (people are the focus rather than objects) and collection-level archival finding aids (collections are the focus rather than objects)
Pawtucket is meant to be customized. The download version includes a basic default theme that supports all functionality but is visually quite plain. By editing the CSS stylesheet and system header and footer templates you can have Pawtucket fit into most any existing design scheme.
Pawtucket is designed to work with an existing Providence database. If you have not already installed Providence you must do so before trying to set up Pawtucket.
Before attempting an installation, verify that your server meets the basic requirements for running Pawtucket:
|Operating system||Linux, Windows (Server 2003, Server 2008, Windows XP and Windows 7 verified to work), Solaris 9+, Mac OS X 10.5+.|
|Server memory||Memory requirements for Pawtucket are lower than for Providence since Pawtucket does not perform media transformations. Any server with 1gig of more of memory should be sufficient. To speed searching and browsing you may want to allocate extra memory to MySQL for caching.|
|Data storage||Pawtucket requires little additional storage over that required by Providence, as it only stores small amounts of user preference data. However, depending upon how you decide to give Pawtucket access to media files stored by Providence, you may (or may) not require storage dedicated to Pawtucket equal to that used by Providence. (See the installation section below for more information)|
|Processor||Any modern CPU should provide adequate performance.|
The core software requirements for Pawtucket are the same as for Providence:
|Webserver||Apache HTTPD version 2.0 or 2.2 is recommended. Other web servers that support the PHP programming language will work as well.|
|MYSQL Database||MySQL Version 5.0, 5.1 or 5.5 will work. Make sure your MySQL installation supports InnoDB tables. CollectiveAccess requires InnoDB support to function properly.|
|PHP programming language||PHP version 5.3.6 or better is required. PHP version 5.4 is supported. You will need to make sure your PHP installation includes the following extensions: ZIP, mbstring, iconv, EXIF, JSON, and MySQL. All of these are configurable options included in the standard PHP distribution and are usually (but not always) enabled in packaged binaries.|
You should also try to have the same media processing software installed as for Providence (of course, if you are running both on the same server this will not be a problem), but this is not required as Pawtucket does not currently accept media uploads.
Configuring PHP prior to installation
Once you have the core software requirements installed on your server you're almost ready to install Pawtucket. But first you will need to take a look at your PHP configuration file and possible adjust a few options.
Your PHP configuration file is usually named php.ini. On Linux systems the php.ini file is often in /etc/php.ini or /usr/local/lib/php.ini. If you cannot find your php.ini file, look for its location in the output of phpinfo(), either by running the PHP command line interpreter with the -i option (eg. php -i) or running a PHP script that looks like this: <?php phpinfo(); ?> The output from phpinfo() will include the precise location of the php.ini file used to configure PHP.
Once you've found your php.ini file, open it up and verify and, if necessary, change the following values:
- memory_limit - sets the maximum amount of memory a PHP script may consume. The default is 128 megabytes which should be more than enough. If you don't want to leave it that high, you should be able to run with the limit set as low as 32 megabytes. If you received memory limit exceeded errors, you should increase this limit.
- display_errors - determines whether errors are printed to the screen or not. In some installation this is set to "off" by default. While this is a good security decision for public-facing systems, it can make debugging installation problems almost impossible. It is therefore suggested that while installing and testing Pawtucket you set this option to "On"
Now that you've got all the requirements in place it's time to set up Pawtucket. You will need to perform the following steps. Note that these instructions assume that you are installing Pawtucket in a subdirectory called "pawtucket" located in the server root of an existing Providence installation. You can also install Pawtucket in a completely separate server root, or make Providence a sub-directory of your Pawtucket installation. You can even install Pawtucket on a completely different server than Providence. All of these options are permutations of the process outlined below.
To install Pawtucket in a sub-directory of an existing Providence installation:
- Make sure you have a working Providence installation. You should have installed it with these instructions.
- Copy the contents of the Pawtucket software distribution to a directory called pawtucket within the Providence server root. If you are to obtain Pawtucket from the project's GitHub repository then run the following command from the parent of the directory into which you want to install Pawtucket:
git clone http://github.com/collectiveaccess/pawtucket.git pawtucket where the trailing "pawtucket" is the name of the directory you want your installation to be in. Git will create the directory for you.
- Copy the setup.php-dist file in your pawtucket directory to a file named setup.php in the same directory. Edit setup.php, changing the various directory paths and database login parameters to reflect your server setup. 'Note: you must specify a valid login to the same MySQL database used by your Providence installation. It doesn't have to be the same login, but it must have full access to the same database.
- Make sure the permissions on the providence/app/tmp directories are such that the web server can write to them. This will allow Pawtucket to generate caches, improving performance.
- By default Pawtucket will serve media uploaded in Providence out of the media directory in the root of its installation directory. To ensure that Pawtucket can find your media create a symbolic link called media from the media directory in your Providence installation to the root of your Pawtucket installation. (If you can't create a symbolic link, either because you're running on Windows or running Pawtucket on a different server than Providence see the next section)
- In a web browser navigate to the pawtucket subdirectory. (If your login to CollectiveAccess/Providence is http://localhost/ca/ then your access to Pawtucket should be http://localhost/ca/pawtucket/)
That's it! There is no installer for Pawtucket. It should run directly.
Pawtucket is by default configured to serve media uploaded in Providence out of its own media folder in the Pawtucket root directory. If you're using a Unix-based operating system (including Mac OS X where they are called 'aliases') and running both Providence and Pawtucket on the same server, the simplest and most efficient way to ensure that Pawtucket can "see" all of the media in Providence is to create a symbolic link from the Pawtucket media directory to the Providence media directory.
If you're running on an operating system that doesn't support symbolic linking such as Windows versions prior to Vista, or are running Providence and Pawtucket on different servers then things get a bit more complicated.
For Windows servers your options are:
- Copy the entire Providence media directory to Pawtucket. This will work but you'll double your storage requirements and have to keep the Pawtucket copy of media in sync with the Providence original.
- Add a third party symbolic linking utility. See this post for additional information.
For users running Providence and Pawtucket on different servers:
- Copy the entire Providence media directory to Pawtucket. This will work but you'll double your storage requirements and have to keep the Pawtucket copy of media in sync with the Providence original. This may not be a bad thing if you are running completely separate installations (including database) as it allows you to present a snapshot of your system the public without exposing your Providence system.
- Mount the Providence media directory on the Pawtucket server using a network file system such as NFS.
If you happen to be running Pawtucket in a subdirectory within the Providence installation you can also edit your Pawtucket app/conf/global.conf to point directly to the Providence media directory. Edit line 65, to point to the media folder in Providence. If your Providence install is in /ca and your Pawtucket install is in /ca/pawtucket then you'd want to change the line to read:
ca_media_url_root = /ca/media/<app_name>
Line 75 may also need a direct path to the media subfolder in PROVIDENCE written all the way from the root such as (remember: you'll need to add YOUR Windows path all the way down to the media directory in Providence):
ca_media_root_dir = d:/Apache2/htdocs/ca/media/<app_name>
What to do if something goes wrong?
If your Pawtucket installation fails, the first thing to do is look at the error messages, if any. If you get a blank white screen, odds are error messages are being suppressed in your PHP php.ini configuration file. Try changing the display_errors option to "On" and then try accessing Pawtucket again.
If you are totally stumped on an installation issue, tell us about it! You can post your questions on the CA support forum at http://www.collectiveaccess.org/forum. Please include a full description of your problem as well as the operating system you are running, the text of any error messages and the output of phpinfo(). We will try our best to resolve your problems quickly.