Procedure to create a new PIE

This is assuming that a working authentication broker is in existence.

A. System set up

1. Create a new Unix user.

  As root, type "adduser [username]".
  Create a password for the user with "passwd [username]".
  You will need this username and password later - do not forget them!
  Check that a home directory has been created for this user by e.g. "ls /home".
  
2. Make this user a postgres user. You can run the PIE with any underlying
database, but we are assuming Postgres for the sake of documentation.

  As a Unix user with permission to create pg users, type
  "[pgpath]/bin/createuser" (where pgpath is the location of the postgres
  installation, e.g. /usr/local/postgres).
  When prompted, "Enter name of user to add", enter username from step 1 ("PIE
  user").
  When prompted, "Enter user's postgres ID or RETURN to use unix user ID", press
  return.
  When prompted, "Is the pie user allowed to create databases", type "n".
  When prompted, "Is the pie user a superuser?", type "n".
  You should now be told that the user has been successfully added.
  
  When prompted, "Shall I create a database for the pie user, type "y".
  
  This database user should automatically have the same password as the pie
  user, and the same name as the pie user for both the access and database name.
  You can test this by typing psql -u and entering the username and password;
  your pg prompt should have the name of the user in it.

  You will need to ensure that:
  a) postmaster (the postgres module communicating with the outside world) is
  run with the appropriate flags to accept external connections. It is probably
  sensible to do this with a shell script that runs
    postmaster -i
  as the user postmaster.
  b) the file pg_hba.conf allows access from the IP address on which the PIE is
  installed - even if this is the same machine. You will need to use a line like
  the following:
    host   all   [IP address of PIE machine]  255.255.255.255 trust
  
  See the postgres documentation for more details.
  
3. Install perl modules CGI, DBI, DBD::Postgres (or the DBD driver for the
database you are using) and Zeta perl. They are all available via
http://www.cpan.org.

4. Set up the resource database for the PIE. (See separate documentation.)

B. Installation of the PIE
  
1. Set up the PIE release in the Unix home directory.

  Copy the file pie-1.1b.tgz into the home directory of the pie user.
  As the pie user, cd to the home directory and type "tar zxvf pie-1.0.tgz".
  
  This should create directories called auth, cgi, config, images, log, perl and
  sql (use "ls" to check this). A copy of this document is also created.
  
2. Make changes to web server configuration to activate new CGI and image 
directory.

  Add the following lines to httpd.conf in the web server configuration
  directory. (The example is for apache.) Pie cgi is what the pie user will
  type into a web browser to access the PIE after the server name, e.g. in
  http://[webserver]/pie/UIG.pl, the pie cgi is /pie.

    ScriptAlias [pie cgi] "[pie user home directory]/cgi/"

    <Directory "[pie user home directory]/cgi">
        AllowOverride None
        Options None
        Order allow,deny
        Allow from all
    </Directory>
    
  Now, add the name of the directory which will contain the images for the PIE
  (these are in the images directory of the installation, but you will also want
  a copy of your institutional logo go be here.) The new lines for this in
  httpd.conf will look like this (for apache).
  
    <Directory "[pie user home directory]/images">
        Options ExecCGI Indexes MultiViews FollowSymLinks
        AllowOverride AuthConfig 
        Order allow,deny
        Allow from all
    </Directory>
    
  Restart the Web server to activate the CGI and image directories. This is done
  for apache with "/usr/local/apache/bin/apachectl restart" (if your apache
  server is installed in the default location).
  
  Note: You may get errors saying that you cannot access the directory if the
  web user cannot read all the directories which come about the pie user home
  directory in the tree.
  
3. Make changes to PIE files as necessary.

  Cd to the config directory, and edit the pie.cfg file. This contains most of
  the local configuration, and contains comments (lines beginning "#") to help
  you to work out what to put here.
  
  Now cd to the cgi directory, and edit the UIG.pl file. In line 16, you
  need to put the full path of the configuration file you have just set up. 
  
  In the same way, you need to edit help.pl to contain the full path of the same
  configuration file, on line 15.
  
  Similarly, in the cron directory, the configuration file location needs to be
  set in all_searches.pl (line 10) and update_searches.pl (line 11). 
  
  Now cd to the perl directory, and edit the access.pl file. Lines 16 and 17
  need to have details of the authentication broker to be used by the PIE.
  
  Finally, cd to the log directory and type:
    chmod a+w pie.log
  to enable logging.

C. Populate the PIE database with initial information.

1. Set up the database structure.

  As the pie user, cd to the sql directory, and log in to postgres. Type 
    \i pie.sql
  and then (when the prompt is returned), type
    \i pieinit.sql

2. Create the HTML pages required by the PIE.

  Continuing the same postgres session, type
    \i htmlconfig.sql
  Type
    \q
  to exit when the prompt is returned again.
  
3. Create a list of resources for the PIE.

  CD to the crom directory, and type
    ./all_searches.pl
  to run the initial setting up of the searches which make up the all resources
  page. This will probably take about half an hour.
 
4. Set up cron jobs to maintain saved searches and update all resources list.

  The scripts all_searches.pl and update_searches.pl need to be run daily. Type 
    crontab -e 
  and then
    o 
  (assuming you are using vi as your default editor - and if you don't know what
  that means then you are!), and then
    0 3 * * * /PATH/TO/CRON/all_searches.pl
  This runs the script daily at 3AM; you may wish to change this if you are
  already running another cron job at the same time.
  To set up a cron job to run update_searches.pl press return to get another new
  line and type:
    30 3 * * * /PATH/TO/CRON/update_searches.pl
  When you exit from the editor (:wq in vi), the changes will be made to the
  cron list, and you should get the message:
    crontab: installing new crontab  
  
D. Test out the PIE.

Your PIE should now be ready to use. Open a Web browser, and type the URL
"[webserver]/[pie cgi]/UIG.pl" and you should be presented with a login screen.
When you log in as any user accepted by the authentication broker, you will see
a new copy of the default page set up by the pieinit script.

You will probably want to add some default resources to the default page; to go there, put the string "?action=present&response=default&userid=[username]" and
you should be able to edit this page.