FAQ
0.5.4
08/02/2006

Running Pixory

Using Pixory

General

What is Pixory?

Pixory is an image (photo) management and sharing application, with the emphasis on sharing. It is a purely web-based application, meaning the only interface to the system is html. Pixory allows an author, with minimal or no work, to create a photo album and share it over the internet, directly from his/her own computer without the need for central servers.

What is Pixory not?

Pixory is not an image editing application like Adobe Photoshop (tm) or Apple iPhoto. It has no user controllable image processing capabilities except for image rotation and the incidental generation of thumbnails. Pixory is also not a photo album "html and thumbnail generator". Pixory does not generate static html pages for inclusion on a web server. Pixory is a true, dynamic web application. For more on this, see the Question: "Where's the html?".

Why does Pixory use an HTML interface? Most "album builders" are native desktop applications!

Pixory aims to provide ubiquitous access to your photos, for both you and the people you wish to share with. HTML is the most portable and universal interface currently available. For instance, Pixory can allow you to browse and show-off your entire album collection remotely, without needing to perform any special preparation ahead of time, from any web browser anywhere on the internet. It also presents the same user interface regardless of mode of access (local or remote). Client applications would be unable to provide this.

How much does Pixory cost?

Pixory is free software.

Does Pixory contain spyware or ads? Is Pixory going to somehow invade my privacy in order to make money?

There is no spyware or adware embedded in Pixory. Pixory does not keep track of its users, does not report on usage to any servers, and does not harvest any email addresses. In fact, Pixory does not do anything that you cannot clearly see in the graphical user interface. Further, Pixory pledges that, under no circumstances, will we engage in any of these nasty activities.

OK, then how do you guys make money?

We don't. Pixory makes no money at all for its authors. It is a hobby of Joe Panico and various other contributors (see the "about" page for a list of contributors).

Is Pixory open source?

Yes, Pixory is licensed under the Gnu General Public License (GPL) version 2. The project is hosted on SourceForge .

I see that Pixory has not yet reached version 1.0-- does that mean it's not stable?

Pixory is quite stable. There have been no reported sightings of major bugs (though plenty of minor ones). Pixory has a fractional version number because the feature set is still changing rapidly.

Where do I get answers to questions not covered in this FAQ?

Send questions here

Running Pixory

What is required to run Pixory?

  • Java 1.4+ or 1.5+ runtime (JRE) installed on your system (Windows/linux)
  • Java 1.4.2+ or 1.5 runtime (JRE) installed on your system (OS X)
  • 64MB RAM (Windows)
  • 75MB RAM (OS X/Linux)
  • broadband always-on internet connection
  • static ip address/domain name or dynamic domain name
  • a little extra free disk space for thumbnail storage-- about 5%-10% the size of the original photo albums

Will Pixory run on the Java 1.5 platform?

Yes since version 0.5.4 it does.

Which operating systems will Pixory run on?

In theory Pixory should run on any Java 1.4 or 1.5 runtime (JRE). However, Pixory has been tested thoroughly only on Windows 2000, Windows XP, OS X 10.4 (tiger), and most major Linux distros that are built on a 2.4+ Linux kernel. There are reports of people successfully running on Solaris. Pixory is known to not run properly on some Linux systems based on the 2.2 kernel. Also, since Pixory relies heavily on multi-threading, we suspect that you will not encounter the best possible user experience while running Pixory on Windows 95, Windows98, or Windows ME, although it may still work. If you are successfully running Pixory on a system that we have not listed here, we would really appreciate it if you sent us an email describing your configuration.

Where do I get the Java Standard Edition (JSE) version 1.4 or later runtime (JRE) for Linux/Windows?

Linux/Windows users click here ->

Where do I get the Java 1.4.2 or later for OS X?

OS X users get it as a Software Update here->

Why doesn't Pixory have an installer?

Installers require a fairly large investment in time and energy, especially when multiple operating systems need to be supported (Windows, Linux, Solaris, etc). We feel that time and energy would be better spent right now in expanding the core feature set.

I don't have a static IP address or domain name. Can I still use Pixory?

Yes! Pixory is intended for just such a scenario. You can easily acquire a free dynamic domain name for your personal server. An explanation of dynamic dns can be found at technopagan, which includes a list of providers at the bottom. A couple of good free dynamic dns providers: www.dyndns.org, www.dynu.com. Once you have a dynamic dns name for your machine, go to the advanced configuration page in Pixory and enter that dns name in the "wan hostname" field.

I have a home network that uses NAT (Network Address Translation) to share a single broadband internet connection. Can I still use Pixory?

Yes! Pixory is intended for just such a scenario. The dynamic dns services listed above will work properly through a home gateway/router performing NAT. You also need to be able to tell your home gateway/router that any requests to Pixory should be routed to the machine that Pixory is running on. This is called "port mapping" and is supported by almost all modern gateway/routers. Find the port mapping configuration for your gateway and configure so that requests for port 8081 go to the machine runing Pixory.

Can I run pixory as a Java Web Application in an App Server?

Yes. Pixory is distributed in two different packagings: as a standalone Java application, and as a Java Servlet 2.3 Web Application. If you want to run Pixory as a "Web Application" you should download the pixory-webapp-x.y.x.zip.

Which Java "App Servers" will Pixory run under?

Pixory has been tested in many Jetty, Tomcat, JBoss and Resin distributions. It should work in any Servlet standard app server.

Can I deploy more instances of Pixory in one "App Server"

Yes you can. However it needs some magic since this needs to be configured outside of Pixory. You can do this by manipulating the web.xml for a 2nd or 3rd instance. It can be found under your webapps folder. From there go to the folder /pixory/WEB-INF. This contains the web.xml. Add the following entries:
  • The <servlet-mapping> <url-pattern>. Since you want to have a different URL for your next Pixory instance.
  • An line containing the pixory_home. As follows: <init-param><param-name>pixory_home This should contain the location where you want all the logging and database related stuff to be stored.
  • An line containing the user_instance. As follows: <init-param><param-name>user_instance. This should contain some unique key. This key is used to identify which pixory_home to use.
Depending on your "App Server" you probably need to restart your webapplication or server. However this feature will change in the future. So no guarantees are made for future extensibility

How do I install the Pixory Java application?

The Pixory Java application doesn't require any installation. Just unzip.

How do I install the Pixory Web App in JBoss or Tomcat?

Acquire pixory-webapp.zip and unzip it. The pixory.war file is a standard web archive that contains everything needed to run Pixory. Hot or cold deploy it into the web application deployment directory for your app server. For JBoss that's: [JBOSS]/server/default/deploy. For Tomcat it's: [TOMCAT]/webapps.

I'm running an older version of Pixory. How do I update to the latest release?

Completely delete the older release. Download the latest release and unzip it.

How do I start the Pixory Java application on Linux or Windows?

On most systems, once you have installed the Java runtime, you can simply double click on the executable jar: pixory.jar. Pixory should automatically launch a web browser window. If that doesn't happen, you can connect directly to Pixory at: http://127.0.0.1:8081/pixory/pxapplication?service=page&context=AlbumBrowser.

How do I start the Pixory Java application on Mac OS X?

The preferred way is to use the Pixory Mac OS X application (application bundle). You can also launch Pixory by hand from a terminal window, but you must use the -Djava.awt.headless=true JVM argument. In either case, Pixory should automatically launch a web browser window. If that doesn't happen, you can connect directly to Pixory at: http://127.0.0.1:8081/pixory/pxapplication?service=page&context=AlbumBrowser.

Can I run Pixory on a system that is not running a window manager (a.k.a. a server, or "headless" system)?

Yes: java -Djava.awt.headless=true -jar pixory.jar

I'm trying to run Pixory "headless" on a Linux system that is not running X-Windows. I specified -Djava.awt.headless=true as a launch property, but Pixory still doesn't work. No thumbnails show up and if I look in the pixory.log file I see error messages about some kind of AWT problem. I thought you said I could run Pixory on a "headless" system?

In a cruel twist of fate, if you want to run Pixory on a headless Linux system, the X11 libraries must be installed. You don't need to actually run X11, but it has to be installed. This is because certain pieces of the Java 2D graphics platform rely on these X11 libraries.

Why didn't Pixory launch when I double clicked the executable jar on Linux or Windows?

When the Java runtime is installed it should configure your operating system so that java is the handler for the .jar extension. If this configuration changes, then your operating system will not know how to make the association between Java and jars. You can always launch Pixory by hand with 'java -jar pixory.jar' from a shell/command line.

Why didn't Pixory shutdown when I closed the browser Window?

Pixory is a server application, even though it runs on your pc. You communicate with Pixory through a web client: a browser. They are separate processes which only communicate through the Pixory web interface.

How do I shutdown Pixory?

On the Logout page there is a pulldown (logout by default) you can use to select a shutdown. However this will only work when executing standalone. When running in a servlet container you can shutdown Pixory by stopping the web application.

Will Pixory automatically restart if I restart my machine?

No.

I'm getting the error: "WAN initialization is not allowed by the current Pixory configuration" What's up with that?

The wan initialization check is a security measure. Suppose that you install Pixory, but before you complete the basic configuration page someone from the Internet navigates to Pixory. They too will get the basic Configuration page and will have an opportunity to complete the configuration and hijack the application. So if Pixory has not yet been "initialized" (had the required fields on the basic configuration page filled in), it checks the ip address of all incoming requests and makes sure that the client belongs to the same LAN as the server that is running Pixory. Here LAN is defined by this subnet mask: 0.0.0.255. The idea is that all machines on the lan are friendly, whereas all machines outside the lan are hostile. To allow wan initialization you have to launch the JVM with this flag: -Dwan.initialization.enabled=true

OK I understand the WAN initialization, but my Pixory instance is hosted and I have no control over JVM flags.

Add a startup servlet to the pixory web.xml file and just put one line of code in the init() method: System.setProperty("wan.initialization.enabled","true");

Using Pixory

Why are there two different graphic designs in Pixory?

You can think of Pixory as two applications in one, though there is only one real application and only one interface. One of these "virtual" applications would be the album composer. This application is used by the person who owns the images/photos and is composing them into albums. The other "virtual" application would be the album viewer. This application is used by visitors who come to look at the albums that the owner has composed. When you start up Pixory, you are in the album composer portion of the application. This includes the Album Browser, Lightbox, Invitation pages as well as all the configuration and control pages accessible from the menus along the top and left sides of the page. When you click on a thumbnail from one of the album editor pages, Pixory "pops-out" the "Album Page" for that picture. The "Album Page" is in the album viewer portion of the application, meaning that it is exactly what viewers see when they come to look at your albums. These viewer pages include the Viewer Home, Album Page, and Album Index, and are accessible to the editor as "pop-outs" so that the editor can immediately see, in a WYSIWYG fashion, the results of editing . In summary, all of the pages in the main window are editor pages, and all of the pages in the little "pop-out" window are viewer pages. Pixory uses a different graphic design for each of the "virtual" applications. Album viewer pages are whitish, with black/grey accents. Album composer pages use a blue/green background with orange highlights.

The graphic layout of the Pixory User Interface looks funny/ doesn't match what I saw in the screenshots.

See the limitations.html file for specifics on which web browsers fully support Pixory. In particular, Apple's Safari web browser does not render the Pixory UI properly. This applies to both the Viewer and Composer sections of Pixory.

Why don't I see picture EXIF metadata in Pixory on OS X? iPhoto shows it!

Pixory cannot display the metadata for photos that have been imported directly from the camera into iPhoto. The problem is that QuickTime 6.4 (which is the jpeg creator for iPhoto 2) embeds Colorsync profiles in the jpegs using a technique which is not compliant with the ICC color profile embedding standard. The work-around is to import photos from cameras/scanners using the OS X Image Capture application. In Image Capture->Options->Download Options *unselect* "Embed Colorsync Profile". Import your pictures to the filesystem using Image Capture. Then you can import these files into iPhoto and Pixory will recognize the metadata.

Can Pixory work with iPhoto albums?

Yes, Pixory and iPhoto can work on the same album set. You can use iPhoto to create albums and select photos for albums, and then use Pixory to add text, captions and to share these albums. If using Pixory in conjunction with iPhoto, it's a good idea to set the Pixory "Image Directory" to {your home}/Pictures/iPhoto Library/Albums. It's a bad idea to scope the Pixory Image Directory to the actual photo directories in the iPhoto Library, because this might interfere with the operations of iPhoto.

Why don't I see any pictures when I try to view some of my picture directories in Pixory?

Not all filesystem directories containing pictures are considered 'albums' by Pixory, and only 'albums' will display pictures in Pixory. Only filesystem directories that have no subdirectories are considered 'albums' by Pixory. Pixory is designed this way to avoid all of the complications associated with nested (hierarchical) albums.

Sometimes the interface seems to display the wrong stuff. For instance, I select an album but Pixory displays a different album or a different page altogether. Is this a bug?

Pixory does not always respond gracefully to the use of the browsers "back" button. You should not use the browser back button in the "Composer" portions of the application-- instead use the navigation that is built into the Pixory user interface. This is not a problem in the "Viewer" portions of the application. Users can safely use the back button on any "Viewer" pages.

Pixory web pages don't seem to be responding properly to my mouse clicks. When I click on a picture/link nothing happens. Or Pixory loses track of my page. Is it broken?

To use Pixory you must have your browser set to enable Javascript and to allow cookies.

Does Pixory support non-Latin based languages/scripts?

Yes. Pixory fully supports all languages/scripts in all areas of the application, including: file names, album names, captions, narrative, etc. All langugaes covered by the Unicode 3.0 specification are handled automatically by Pixory, and you can even mix different languages on the same page! The list of supported languages includes, among many others: Japanese, Korean, Chinese, Hindi, Russian, Arabic, Hebrew, Turkish, Bengali, Greek, Gujarati, Hmong, Thai, Punjabi, Urdu, Tagalog, Tibetan, Ukranian, and Vietnamese.

Is Pixory localized for languages other than English?

Yes. Pixory has been localized for German. If you would like Pixory localized for your native language, please volunteer to translate some text.

I clicked on a link/icon in Pixory and the app seems to have "blown up", meaning the background color disappeared and the layout is now messed up. Is Pixory broken?

Ahh, you must be a) using Mozilla earlier than version 1.2, and b) impatient. Mozilla (up to 1.1 inclusive) has a bug that manifests itself when you click on a link in a web page before that webpage has finished completely loading. You should wait for all pages (including all images) to completely load before clicking on anything when using Mozilla. This bug is fixed in the 1.2+ versions of Mozilla.

I clicked on a link in the composer and pixory zapped me to the login page (oh yeah, I might have gotten a cup of coffee right before that click). Why did pixory do that?

Pixory keeps track of inactivity (time during which you do not click on anything) and will log you out of the application after 60 minutes of inactivity. This value is not configurable.

Some of the scaled images that Pixory produces have the wrong colors. But other programs are able to thumbnail the originals without any problems and the full-size images shown by Pixory have the correct colors. How do I correct this?

This usually happens when the images have first been manipulated in some kind of an image processing program, such as Paint Shop Pro or Windows XP FAX and Image viewer. The problem is caused by a bug in Java Runtimes earlier than 1.4.2. If you are experiencing this problem, upgrade your Java Runtime (JRE) to version 1.4.2 or later.

Will Pixory modify any of my pictures?

No, Pixory never modifies any originals. Pixory has taken the hypocratic oath-- do no harm!

I forgot my password, how do I reset it?

Shutdown Pixory. Restart Pixory with the -Dpassword.reset=true option: i.e. java -Dpassword.reset=true -jar pixory.jar. When Pixory launches it will throw you into the Basic Configuration screen, where you can change your password.

Is the embedded FTP server a general purpose FTP server? Will it allow 3rd party or anonymous FTPs?

No, the embedded FTP server is a highly specialized FTP server that is coupled to the web interface. It will not allow 3rd party logins or anonymous FTP. The embedded FTP server will only allow logins through the web interface. It achieves this by: 1) only allowing logins by users who are currently logged into the web application. 2) using as a passord for that user the session id from the web application session. Thus, the embedded FTP server is very secure.

I seem to be limited to using only 1 album at a time. Do I have to go to the configuration page and reset the "image directory" every time I want to change albums?

No. The "image directory" setting in the configuration is the top-level parent of all your album directories. So your album directories can be arranged in any arbitrary hierarchy, but they must have one parent. For best performance, you should set the parent so that the only directories under it are directories you want to use as albums. Pixory, from time-to-time, will scan all of the directories beneath the "image directory" and the less work it has to do the better.

Where is the HTML stored?

Pixory does not store HTML. Pixory is a dynamic web application, which means that every web page is generated on-demand for each client. This ensures that all changes made to album content, permissions, etc, are always immediately reflected to all users.

Why is the documentation so crappy and out of date?

Pixory's feature set is changing pretty quickly, so we are not maintaining high quality documentation right now. However, we are carefully maintaining this FAQ, and if you discover an inaccuracy or deficiency please let us know.