README for Xperience, Inc.'s Portal 0.4.00.
Created by James A. Pattie (james@pcxperience.com)

The Portal is the framework for all applications that Xperience, Inc.
is currently creating or will create that are Web based.

The Portal takes care of logging a user in, setting up their main session,
presenting them with their desktop (list of applications available to them), and
then runs any applications the user wishes.  The Portal is the only cgi script
that is run.  It sources and calls methods in the specified application to 
actually do the work.

Goto http://www.pcxperience.org/index.html#debian-apt to get the latest version
of the portal and all dependancies.  The modules packaged as .debs are only 
done as a conveniance and are not supported/maintained by us unless they are 
our software.

Required Files/Perl Modules (as of 0.2.00 we are now using XML::LibXML for config files):
  libxml2 2.4.22 (Needed by XML::LibXML)
  File-Temp 0.12 (Needed by XML::SAX)
  XML::SAX 0.10 (Needed by XML::LibXML and XML::SAX)
  XML::NamespaceSupport 1.07 (Needed by XML::LibXML)
  XML::LibXML 1.51
  DBIWrapper 0.20
  HTMLObject 2.27
  Digest::MD5 2.16
  Apache::Session 1.54
  Crypt::CBC 2.02
  Crypt::IDEA 1.01
  Storable 1.0.14
  MIME::Base64 2.12
  DBI 1.20
  DBD::Pg 1.01
  Time::Local 1.04
  Date::Manip 5.42a
  SOAP::Lite 0.55+
  Compress::Zlib


NOTE:  All debs are built on an updated Debian testing box with perl 5.8.4.

Installation:  (non-deb method)

  tar xvzf libpcxportal-perl-{VERSION}.tar.gz
  cd libpcxportal-perl-{VERSION}

  perl Makefile.PL
  make
  make test
  su (if not root)
  make install

  tar xvzf pcxportal-{VERSION}.tar.gz
  cd pcxportal-{VERSION}
  cd install
  ./setup.sh

  Read the INSTALL file (either in install or in the documentation directory
  if using debs) if having problems with the database setup code.

  ****************
  After you install the CompanyAdmin Portal app, you can then manage users 
  and applications for your company via the web interface.
  ****************


  The install directory contains the following scripts which will also be put
  in /usr/lib/pcx_portal/ when the install.pl script is run.

  install.pl - This will make the directories in the web server and do initial
            configuration.
  scripts/setup.pl - Configuration program which actually modifies the 
            Portal.xml file in /etc/pcx_portal to configure what the portal 
	    uses/looks like.
  scripts/setupDB.pl - Attempts to help automate the creation of the portal and
            billing databases and gives step by step instructions (with valid
            examples) of what needs to be done to create the users and grant
            them access to the databases.
  scripts/create_default_account.pl - This will create the default company and
            system administrative user account.
  scripts/create_company.pl - You can create other companies in the Portal.
  scripts/session_check.pl - This script helps the migration from Database
            Sessions to File Sessions go a little more smoothly for the
            administrator.  You need to run setup.pl to do the actual switch
            first.
  scripts/convertConfig.pl - This script converts the old Config.pm config
            files to the new XML config format.  The new layout for config
            files is to be /etc/pcx_portal/{AppName}.xml where {AppName} is the
            name of the Application.  {AppName} = Portal if dealing with the
            Portal itself.
  scripts/convertConfig.sh - This is a wrapper script around convertConfig.pl 
            which will hopefully make the package management code cleaner.  
	    Also, the user can call this to more easily convert config files as
	    long as they are in the standard locations.
  scripts/colorSchemeInstall.pl - This script installs any ColorScheme XML 
            files it finds for the specified Portal app into the Portal and 
	    does any work needed to make sure that any user derived 
	    ColorSchemes are updated with any additions or deletions.
            Usage: colorSchemeInstall.pl --appname {AppName}
            {AppName} can be Portal (to install the Portal's ColorSchemes) or
            any other valid Portal app.
  scripts/updateDBSettings.pl - This script updates the Portal database based
            upon what the application has specified via the DBSettings.xml
	    file the app provides.  config, event, dynamic-content and 
	    rights (permissions) can be created, updated and deleted via this
	    tool.
	    Usage: updateDBSettings.pl --appname {AppName}
	    {AppName} can be Portal (to work with the DBSettings.xml file the
	    Portal provides) or any other valid Portal app.
	    The DBSettings.xml file is looked for in the following place:
	    {webRoot}/{siteDir}/install/{AppName}/DBSettings.xml
	    Where {webRoot} and {siteDir} are from the Portal Config and default
	    to /usr/share/pcx_portal/portal.

Installation: (debian method)
  point to the stable debian repository at 
  http://www.pcxperience.org/index.html#debian-apt
  ** Only point at the unstable repository if you want to beta test new versions
     of the Portal being developed.

  apt-get update
  apt-get install pcxportal

  apt-get install pcxportal-<APP>
  when you want to install other Portal apps.

  Currently available Portal Apps are:
  pcxportal-xiwa - XIWA our Accounting application
  pcxportal-companyadmin - Lets a Portal Company Admin Manage their Users and 
  	assigned Applications.
  pcxportal-user-properties - Lets a Portal User tweak their settings
  pcxportal-example - A sample Portal App to use as the basis for your own

  ***********************

After installation the portal will be at http(s)://server/portal/index.cgi

Web Server Notes:
***** New as of PCXPortal 0.3.00 ***********
In your httpd.conf file add:
Include /etc/pcx_portal/apache/apache.pcxportal

in the section you want the /portal alias and <Directory> block setup.
This points to the portal being installed at /usr/share/pcx_portal/

Note: You can run /usr/lib/pcx_portal/setupApache.pl to automate this for you.
This may be broken on non-Debian based systems.

If you put the Portal in a different location, make sure to modify the include
file to reflect your changes.

The portal relies heavily on .htaccess files working to turn on ExecCGI support
and mod_perl support in the cgi-bin directory, etc. and to disable access and
other things in other directories.

If you don't want mod_perl running then edit the .htaccess file in 
portal/cgi-bin and comment out the 3 lines that are as follows (using #):

  Sethandler perl-script
  PerlHandler Apache::Registry
  PerlSendHeader On

You should restart Apache anytime you update an application in the Portal and
are using mod_perl so that it gets the latest changes.

*****************

NOTE:  When upgrading from 0.2.xx to 0.3.xx the app_tb, app_servers_tb and
company_app_tb tables had the db_host field added and it defaults to 127.0.0.1.
If this is wrong, you will need to manually fix the entries in the database.


NOTE: If you were using a cvs version of 0.3.00 and installed the Portal web
content into option 0 (/usr/lib/pcx_portal/www) then you need to convert and
point to the new option 0 (/usr/share/pcx_portal).  Make sure any db_dump
files are moved over after you re-install the UserProperties and XIWA apps.
Once all your apps have been re-installed and are pointing to the now correct
location of /usr/share/pcx_portal, you can delete /usr/lib/pcx_portal/www.


NOTE: When going from any version to 0.4.00, be aware that boolean values of
true/false are now expected to be 1/0.  The setup scripts have been fixed to
ask you for boolean values as y/n/Y/N, but internally it is 1/0.

*****************

