README for Xperience, Inc.'s Portal 0.2.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. The Portal will provide the following Objects: Session, SessionHandler, Auth, Desktop, Applications, Language, Log, Methods and Portal. Data Objects will be created in the Objects directory to define Companies, Users, Applications, etc. The Session object will provide an interface to the Apache::Session module to provide session persistence. Each application and each portal that is on another machine will have their own session started on their machine but all portals will be made aware through the use of the global session_id cookie. The SessionHandler object will encapsulate multiple Session objects to allow the portal to easily manage multiple applications having sessions on the server. The Auth object will provide the interface to authenticate a user and allow the portal to determine what permissions they have. The Desktop object will present the user with their customized desktop. All applications that they are allowed to use will be displayed and will be grouped by function (administration, help, news, bugs, regular apps, global apps). The Applications object will present a list of available applications the user is allowed to work with. The Desktop object will use this object extensively. The Language object will provide transparent translation of phrases to the desired language. The Log object will provide the interface to log events in the portal. The Portal object will be called when the app=Portal is specified. It coordinates what the portal does for itself. Goto http://www.pcxperience.org/apt/ to get the latest version of the portal and all dependancies. The modules packaged as rpms 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.17 HTMLObject 2.16 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 NOTE: All rpms are now built on an updated RedHat 7.3 box using perl 5.6.1. If you need older versions of perl, rebuild the src rpm via rpm --rebuild pcx_portal-0.2.X-R.src.rpm (where X = version, R = release) and then install the resulting rpm file. Installation: (non-rpm method) tar xvzf pcx_portal-{VERSION}.tar.gz perl Makefile.PL make make test su (if not root) make install cd install ./install.pl Run /usr/lib/pcx_portal/setup.pl to configure the Portal. Read the INSTALL file (either in install or in the documentation directory if using rpms) and then run /usr/lib/pcx_portal/setupDB.pl to do the actual DB creation. Next you need to create the default company and administration user for the Portal. Run /usr/lib/pcx_portal/create_default_account.pl. Then you need to import any ColorSchemes that were defined for the Portal. Run /usr/lib/pcx_portal/colorSchemeInstall.pl --appname Portal 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 Config.pm 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/create_user.pl - Will add a user account to any of the companies configured in the portal. This will be removed once the add user app is created. 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/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. Installation: (rpm method) rpm -Uvh pcx_portal-X.Y.Z-i386.rpm X = major version number (currently 0). Y = database version number (currently 2). Z = code release number (patch level). The rpm is created for a RedHat 7.3 box and will put the Perl Modules in the perl tree, the web related helper content in /var/www/html/portal and the support scripts in /usr/lib/pcx_portal. Documentation will be in /usr/share/doc/pcx_portal-X.Y.Z *********************** Optionally you can install using apt by pointing to our Portal apt repository. Add the following line to your /etc/apt/sources.list file: rpm http://www.pcxperience.org/apt redhat/portal/en/i386 perl5.6.1 This apt repository currently only contains perl 5.6.1 packages. perl 5.8.0 packages will eventually be made, though no guarantee on when since we are not yet moving to perl 5.8.0 (RedHat 8.0). *********************** The portal will be available as http(s)://server/portal/index.cgi Web Server Notes: 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. To make sure that .htaccess files will work you have 2 options: 1) in the block for the html root directory (/var/www/html) set AllowOverride to All or 2) Create a block specifically for the portal (/var/www/html/portal) and set AllowOverride to All in it. 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.