- Home
- Documentation
- Download
- Known Issues
- Project License
- Jira (No longer available)
- Bamboo (No longer available)
 | Project Status Please note that this project is no longer active. If you are interested in taking over the code base please let me know. |
Description
The following are instructions on how to install and manage the application.
Java Setup
Download Java JRE from Sun
http://www.java.com/en/download/index.jsp
Please follow the instructions provided by Sun.
Java Advanced Imaging API
Download the Java Advanced Imaging (JAI) from Sun.
 | Version 1.1.3 should be at the top of the page, version 1.1.4 hasn't been released yet.
Scroll down to your Operating System, there should be 4 versions. If you installed the JRE in the previous "Java Setup" step then download the JRE version. If you installed the JDK in the previous "Java Setup" step then download the JDK version. The other two version are there if you want to manually install the JAI libs. |
https://jai.dev.java.net/binary-builds.html
Install the package that corresponds to what you installed in the "Java Setup" step.
Servlet Container
Pix has been tested with Apache Tomcat and Caucho Resin, but any serlet container should work.
Specifically, the following servlet container versions have been tested:
| Application Server | Version | Status |
|---|---|---|
| Apache Tomcat | 5.5.23 |  |
| Resin Pro | 3.1.3 |  |
| Resin Pro | 3.0.23 | |
| Jetty | 6.1.5 | |
Increasing memory for Servlet Container
If you do not you will get java.lang.OutOfMemoryError: Java heap space errors.
 | It is recommended to increase the memory for the servlet container to at least 128MB. This is because the transformation of the images can be quite memory intensive. |
| Application Server | Instructions |
|---|---|
| Apache Tomcat Windows | Edit the catalina.bat and add SET CATALINA_OPTS=-Xmx128m above rem Get standard environment variables. |
| Apache Tomcat Unix/Linux/OS X | Edit the catalina.sh and add CATALINA_OPTS=-Xmx128m above # OS specific support. |
| Caucho Resin | Call resin with the arguement of -Xmx128m, eg httpd.sh -Xmx256m |
| The location of the servlet container should have enough drive space for the images you want to host. |
Pix installation
To install, copy the pix war file into the servlet container webapps folder and start the servlet container.
| It is recommended to rename the pix war from pix-X.X.war to pix.war as the directory that will be created will be named after the war file. |
The war file can be downloaded from the Download page
Administration and security
The application has a single administration account, this account is used to upload the images, set image metadata and manage the application. The default username is admin and the default password is password.
To change the password, login as admin and click on Setup in the footer. On the Setup page enter the current password and the new password twice.
| It is strongly advised to change the default password. |
General Application Details
The application will save the uploaded images in the Data Directory (see Setup page below). There it will create a series of directories starting with roll. In the roll directory three folders are created, 'raw', 'web' and 'thumbnail'. Any metadata provided in the Upload page is stored in the database.
The application stores the uploaded images the 'raw' folder and automatically scales the raw images to create thumbnail and web sized images.
Setup page
When logged in as admin, a setup link will appear in the footer. Clicking on this link will bring up the Setup page.
Both the image files and database files are stored in the Data Directory. This should be a location where the Servlet Container has write access.
The Data Directory must be an absolute path, eg C:\pix-data\ or /var/www/data/.
Upload page
When logged in as admin, an Upload link will appear in the footer. The Upload page allows the creation of a new group of images or adding images to an existing group.
Image Rotation
When logged in as admin, below the images in the ShowTag page will appear 0 90 180 270 links. Each of these links will rotate the image the webimage and thumbnail corresponding degrees. The raw file is never changed.
| After rotating an image, the browser may have a cached image, refresh the page to see the updated image. |
Upgrading: 1.9 and later to 1.12
Move old pix directory out of the webapp directory, copy new war into webapps, start the servlet container and configure Application directory.
Upgrading: 1.8 and earlier to 1.9
| Please be aware the the Java Advanced Imaging API is now required to be installed on the server. |
To upgrade, move your data directory (by default at webapps/pix/WEB-INF/data) out of the pix directory. This will allow you to upgrade by backing up the old pix folder and dropping the new war in.
An upgrade might look like this in Linux/Unix/BSD/OS X:
The old pix directory must be moved from the webapps directory, otherwise the serlet container will try and start it.
Copy the new pix.war to the webapps directory and start the servlet container. Login as admin with the default password, goto the Setup page and change the Application Directory to ../data/. Finally, change the default password.
After the upgrade is complete and working correctly, the backup of the old pix directory can be deleted.