If you are feeling lucky, you can now start the PIA with the command:

./PIA/bin/pia ./PIA/Doc

You should see some initialization messages ending with
 Point your browswer to <URL: some URL>
which indicates that the server is up and running.

Assuming all went well, you can now click on the following link: http://localhost:8888/ to point your browser at the PIA, which is now running as an ordinary web server, serving up its own online documentation from the directory you gave it on the command line.

If that didn't work, try reading the next section on Initial Setup, possibly followed by the section on Troubleshooting in Using the PIA. It's likely that all you need to do is set the PIA_HOME and PIA_ROOT or HOME environment variables.

If it did work, you should now try to start the PIA in its default configuration, with its full complement of standard sample applications -- the PIA is more than just a web server: you can also build complete applications out of active web pages, and we provide a few examples. Try the command:

./PIA/bin/pia

Browse to http://localhost:8888/Doc/install.html to continue reading this document.

The next section will explain what's happening, but the bottom line is that the PIA has looked in its default root directory, PIA_HOME, read the default configuration file there, _subsite.xcf, and set itself up as an application server. You can also specify the PIA's complete configuration in a single file; some examples can be found in Config/Site/.

At this point, you can do one of three things:

1. Go on to the next section to find out how to set up your environment variables to make the PIA easier to use.
2. Read the online documentation.
3. Play with the PIA some more.
   This is the recommended method for getting acquainted with the capabilities of the PIA. In particular, /Agents/Tutorial/ and /Samples/) demonstrate the unique properties of the PIA's server side XML-based markup language, while /Agents/SimpleCalendar represents a typical application.

There are three prerequisites to successfully running the PIA web server:

1. A Java Virtual Machine (JVM) must be installed. The PIA startup scripts expect that the java program is accessible through your PATH environment variable.
2. The PIA's class files and other files distributed with the PIA must be accessible. The startup scripts expect to find the class files in the src/java subdirectory of the PIA's ``home directory'' (PIA_HOME -- the directory in which the PIA was installed). Note that in the default configuration, PIA_HOME is also used as the "virtual root" directory for the server. (See below for an explanation of virtual roots.)
3. A ``root directory'' where pages are served from and where applications can write data files. This is called the PIA's ``root'' directory, or PIA_ROOT. Note that in the default configuration, this is a specified as ~/.pia

Values for PIA_HOME and PIA_ROOT can be specified in environment variables or on the command line. (See Using the PIA.) Various other variables can be specified on the command line or in the configuration file.

Virtual Root directory

In many Web applications, it is desirable to have a core set of pages that are the same for many different sites intermingled with some pages that are customized for a particular site. Normally one would like to update the shared pages using a tool like CVS without affecting the locally customized pages. The PIA Web server makes this kind of operation very easy to using the concept of a "Virtual root directory." When the Web server receives a request for a page, it first looks in the "real" root directory, PIA_ROOT. If they requested page does not exist in that hierarchy, then the server looks in the "Virtual root" hierarchy (if one has been specified).

In the default configuration, PIA_HOME is specified as the "Virtual root." This makes it easy to use the sample applications and update them using CVS while allowing you to make customizations in PIA_ROOT. Note that when a PIA application needs to store a file on disk, it does so under the PIA_ROOT hierarchy. (Note that PIA_HOME could even be on CD-ROM because the PIA never tries to write files there!).

Experts only: The directory PIA_HOME, as described above, actually refers to two funtionally different locations, which can be addressed separately. One is where the java classes and executables live; that is always and forever PIA_HOME. The other location---the "virtual root,", is where the PIA looks for applications it can't find in PIA_ROOT---can in principle be any directory. You can set the virtual root to be some third directory by using the -vroot command-line option when starting the PIA, but we don't recommend it for beginners... not only is it confusing, but your PIA server would no longer have access to cvs-updated applications in the Agents, Samples, and Contrib directories.

In summary, the PIA look for its java class files under PIA_HOME, and the web server looks first for applications/pages in PIA_ROOT then in the virtual root.

As a consequence of this arrangement, we recommend you don't edit anything in PIA_HOME, which is automatically updated/overwritten by CVS, unless you are actively working on the PIA codebase or improving the sample applications. Instead, write everything under PIA_ROOT (e.g. ~/.pia).

Most people will develop applications by making a new subdirectory of PIA_ROOT/Agents/, then copying in pages from the PIA/Samples directory or from other applications.

The default values for these variables should work in most cases:

The executable scripts (e.g. bin/pia) attempt to set the PIA_HOME variable based on the location of the script or the current working directory. But if you want to run the pia from a different location, or run a different version, you may have to explicitly set this variable to the location of the PIA directory you just installed.

The directory PIA_ROOT can be set on the command line with the -root option, or by setting the environment variable PIA_ROOT. On Unix, the default location for PIA_ROOT is ~/.pia. On Windows, the default directory is %HOME%\pia if HOME is set, otherwise c:\PIAUSERS\username (if a username is not available nobody is used).

If you use the -root or -home command line option to specify PIA_ROOT or PIA_HOME, that setting takes precedence over the one you specify in the corresponding environment variable.

It is convenient to put the directory PIA_HOME/bin, which contains scripts (including the one that implements the pia command!) into your shell's search path. You may also want to specify a different root. On Linux you can do all of this by putting the following into your ~/.bash_profile file:

  # The following line will change depending on where the PIA is installed
  export PIA_HOME=$HOME/PIA
  export PATH=$PIA_HOME/bin:$PATH
  export PIA_ROOT=$HOME/.pia

This setup is not necessary if you always run the PIA using the command ``PIA/bin/pia'', but most users find this to be inconvenient.

You may also need to set up Java's CLASSPATH environment variable. The PIA's wrapper script will try to set one up for you, but whether it succeeds will depend on how clever your java implementation is. You don't have to have PIA_HOME/src/java in your CLASSPATH; the wrapper script is smart enough to add it for you.

In addition, if you don't like the way this document looks because the difference in size between large and small fonts is too great, consider adding the following line to your .Xdefaults file. Adjust the number to suit yourself; the default is 20 (percent).

  Netscape*documentFonts.sizeIncrement:	15

• See the Quick Start section for the commands for running the PIA without setup.
• If you have done the initial setup described above, you should be able to use the command pia by itself.
• pia -help will display all of the command-line options
• See Using the PIA for more information, including the available command line and configuration file options.

On UNIX or Linux, once you have set up the PIA_HOME and PIA_ROOT environment variables and put PIA_HOME/bin in your search path as described in the previous section, you should be able to start the PIA with the command: ``pia'' A complete list of command-line options can be found by running $PIA_HOME/bin/pia -help at the shell prompt.

Under Windows 9x and NT, launch the PIA in a DOS window with the command: PIA_HOME/bin/pia.bat -- this is a batch file that makes use of the PIA_HOME and PIA_ROOT environment variables, and is similar in function to pia_wrapper on Unix.

Using the PIA

The PIA acts as a Web server. Assuming you have gotten the PIA to run in its default configuration, you should now be able to browse to http://localhost:8888/ in order to access the PIA's own web pages.

If the default configuration is different and you have run the PIA from a command line, it will have printed out a line like:

  Point your browser to <URL: http://blackroot.crc.ricoh.com:8001>

after initializing, and you can cut-and-paste the URL on that line into your browser and go from there.

There are some applications---such as a browser proxy and browsing-history system---which require that your browser use the PIA as a proxy. This enables the PIA to process any incoming and outgoing pages as you would like. See the Proxie agent for more details.

It is also possible to use the PIA ``off line'' from the command line, as a pure document processor. See Using the PIA.

See the section on Troubleshooting in Using the PIA if you're having problems getting the PIA started, or if it does something unexpected.

You can check for known bugs by going to http://www.risource.org/PIA/

Questions, problems and comments should be directed to PIA-bugs@risource.org.