COSMOS v1.0 INSTALL.txt
=======================

9/15/2005


General knowledge of installing, configuring, and operating Apache,
SSL, PHP, and MySQL applications is assumed.

Prerequisites:

Before proceeding install these external prerequisites- they are not
included in this package:

- Linux (we've tested only with RedHat; most any Unixish OS should work)
- Apache web server (2.x works fine)
- PHP 4.3.2 or later (as an Apache module)
  - PHP must be compiled with support for MySQL and gd with FreeType
- MySQL 3.23.58 or later (MySQL 4.x should work also, but is untested)
- gd-1.8.4
- freetype-2.1.4
- jpGraph
    - Note that jpGraph is licensed for non-commercial, open-source or
    educational use under the QPL 1.0 (Qt Free License); other use
    requires purchase of the professional version (see the jpGraph
    website at http://www.aditus.nu/jpgraph/).
    - versions 1.7 and 1.19 have been tested. 
    - jpGraph also requires a separate fonts package: see "TTF Fonts
    for use with jpGraph" in jpGraph docs, see also:
    http://corefonts.sourceforge.net/
- PHPlib 7.4
    - try http://phplib.sourceforge.net/
- sendmail (or compatible MTA)


PHPlib setup items:  
  
PHPlib source code is under the PHP directory of the unpacked PHPlib
distribution. The PHPlib source code path must be in your PHP
configuration's 'open_basedir' and 'include_path' directives. (See
'Apache setup items' below.)
    

jpGraph setup items:
  
In the file, <jpGraph-root>/src/jpg-config.inc, set the 'read cache' to
false: 
    DEFINE("READ_CACHE",false);    
  
The jpGraph source code path must be in your Apache configuration's
'open_basedir' and 'include_path' PHP directives. (See 'Apache setup
items' below.)

Install the core TTF fonts available at
http://corefonts.sourceforge.net/.

In the file, <jpGraph-root>/src/jpg-config.inc, set the TTF directory
to point to your installation of the TTF fonts- for example:

 DEFINE("TTF_DIR","/data/www-data/test/cosmos-root/fonts/jpgraph/ttf/");

Your Apache configuration's 'open_basedir' PHP directive must also
allow access to the TTF directory. (See 'Apache setup items' below.)
         

MySQL setup items:

- Create the MySQL database, for example:
  mysqladmin -uroot -p create cosmos_test_db

- Create the initial database tables & initial data

    - Initial necessary SQL data:
    
    <cosmos-distro>/sql/cosmos_initial_demo_db.sql

    The Demo DB includes demo users, demo agencies, demo programs and
    demo services. It does not include any persons, households, etc.

    You might create the initial demo data by executing:

    cat <cosmos-distro>/sql/cosmos_initial_demo_db.sql | mysql -uroot -p cosmos_test_db 

- Create three MySQL accounts & set their permissions for the COSMOS
application:
        
    1 - A MySQL read-only user used by the public site:
    
        User: cosmos_ro
        MySQL allowed perms: SELECT on AGENCY, PROGRAM, SERVICE, and
            CODES 
        MySQL not allowed perms: All except SELECT perms should not
            be allowed, and although the public site application code
            does not make requests to private information tables, as a
            safety measure the public site should not be given access
            to the tables that hold private information. 

        Using bash shell, you might do something like this to create
        this MySQL user:
        
        DBNAME=cosmos_test_db
        DBUSER=cosmos_ro
        DBPASS=<specify-your-cosmos_ro_passwd>
        echo "grant SELECT on ${DBNAME}.agency to ${DBUSER}@'localhost' identified by '${DBPASS}';"| mysql -uroot -p mysql        
        echo "grant SELECT on ${DBNAME}.program to ${DBUSER}@'localhost' identified by '${DBPASS}';"| mysql -uroot -p mysql        
        echo "grant SELECT on ${DBNAME}.service to ${DBUSER}@'localhost' identified by '${DBPASS}';"| mysql -uroot -p mysql        
        echo "grant SELECT on ${DBNAME}.codes to ${DBUSER}@'localhost' identified by '${DBPASS}';"| mysql -uroot -p mysql        

    2 - A MySQL user with update permissions:
    
        User: cosmos_update:
        MySQL allowed perms: SELECT, INSERT, UPDATE, DELETE, CREATE
        MySQL not allowed perms: DROP, REFERENCES, INDEX, ALTER,
            RELOAD, SHUTDOWN, PROCESS, FILE

        Using bash shell, you might do something like this to create
        this MySQL user:
        
        DBNAME=cosmos_test_db
        DBUSER=cosmos_update
        DBPASS=<specify-your-cosmos_update_passwd>
        echo "grant all privileges on ${DBNAME}.* to ${DBUSER}@'localhost' identified by '${DBPASS}'; revoke drop,references,index,alter,reload,shutdown,process,file on ${DBNAME}.* from ${DBUSER}@'localhost';"| mysql -uroot -p mysql        

    3 - A MySQL user with administrative permissions:
        
        User: cosmos_adm:
        MySQL allowed perms: SELECT, INSERT, UPDATE, DELETE, CREATE,
            DROP, REFERENCES, INDEX, ALTER
        MySQL not allowed perms: RELOAD, SHUTDOWN, PROCESS, FILE      

        Using bash shell, you might do something like this to create
        this MySQL user:
        
        DBNAME=cosmos_test_db
        DBUSER=cosmos_adm
        DBPASS=<specify-your-cosmos_adm_passwd>
        echo "grant all privileges on ${DBNAME}.* to ${DBUSER}@'localhost' identified by '${DBPASS}'; revoke reload,shutdown,process,file on ${DBNAME}.* from ${DBUSER}@'localhost';"| mysql -uroot -p mysql 
                     
- Other MySQL related items:
    - Review your MySQL configuration file, typically /etc/my.cnf
    - We recommend using phpMyAdmin for easier management of your
    MySQL database, but take care to secure it so it is only accessible
    by the necessary administrators.
      

PHP setup items:

- PHP config file:

The following settings are recommended or required to be included in
your PHP configuration file, typically /etc/php.ini. You should
optionally be able to set at least some of these on a per virtual host
basis via Apache configuration.

NOTE: We do not recommend running COSMOS without safe_mode on, and we
do recommend running PHP as an Apache module.

    - Recommended php.ini settings:
    
    expose_php = Off
    max_execution_time = 30 ; Maximum exec time of each script, in secs
    max_input_time = 60     ; Max time request parsing time
    memory_limit = 8M       ; Maximum memory a script may consume (8MB)
    log_errors = On
    allow_url_fopen = Off
    register_globals = Off

    - Required php.ini settings:
    
    safe_mode = On
    safe_mode_gid = On
    engine = On
    short_open_tag = On
    safe_mode_exec_dir = /usr/local/lib/php-secure-bin ; or your choice
    variables_order = "EGPCS"
    gpc_order = "GPC"
    magic_quotes_gpc = On
 
- Other PHP related requirements & settings:

The safe_mode_exec_dir defined in your php.ini must contain a symlink
to your sendmail (or compatible MTA) executable.


Apache setup items:

There are two separate websites, and code for each, sharing the same
database. One is for private use and is used to manipulate client
records. This application is referred to as the "COSMOS Client
Information System" (CCIS) or "the private site". In the distribution
archive this site is rooted at the "private" directory.

The other code tree provides a searchable public interface to programs
and services. This application is referred to as the "COSMOS Online
Resource Guide" (CORG) or "the public site", and is rooted in the
distribution archive at the "public" directory.

You must configure a separate Apache virtual host for each code tree. 

The "Client Information System" uses data stored in a MySQL database.
The public "Online Resource Guide" uses the same database, but only has
inquiry access to the agency, program, service, and codes tables.

You must run the Client Information System with an SSL-served website
to protect the privacy of the information exchanged between the client
web browser and the web server.


Apache configuration for the public "COSMOS Online Resource Guide"
application:

- Add index.php to the Apache configuration directive 'DirectoryIndex'.

- Configure the Apache vhost DocumentRoot directive to point to the
root of the public code tree. For example:

    DocumentRoot /cosmos-root/cosmos-distro/public

- Configure application environment variables, for example:

   # Environment variables used by the COSMOS application,
   # see public/include/demo-test-setup-public.inc under "Application
   # setup items" in INSTALL.txt
   SetEnv CLIENT_GRP demo
   SetEnv CLIENT_MODE test     

- Configure Apache PHP settings for doc_root, open_basedir and include
path to allow access to the Online Resource Guide code, PHPlib, and the
include directory of the COSMOS public code tree. (Note that the public
site does not need access to jpGraph code.) For example:

   # PHP items
   php_admin_value doc_root "/cosmos-root/cosmos-distro/public/"
   php_admin_value open_basedir ".:/cosmos-root/cosmos-distro/public/:/cosmos-root/cosmos-distro/lib/:/cosmos-root/phplib/"
   php_admin_value include_path ".:/cosmos-root/cosmos-distro/public/include/:/cosmos-root/cosmos-distro/lib/:/cosmos-root/phplib/"
   php_admin_value register_globals Off

- Disallow certain files to be served directly to the web browser:

   # Don't allow '.inc' or '.ihtml' files directly via browser
   <LocationMatch "\.inc$">
     Order deny,allow
     Deny from all
   </LocationMatch>

   <LocationMatch "\.ihtml$">
     Order deny,allow
     Deny from all
   </LocationMatch>

 
Apache configuration for the private "COSMOS Client Information System"
(CCIS) application:

- Make sure the CCIS application is implemented as an SSL-protected
website.

- Add index.php to the Apache configuration directive 'DirectoryIndex'.

- Configure the Apache vhost DocumentRoot directive to point to the
root of the private code tree. For example:

    DocumentRoot /cosmos-root/cosmos-distro/private

- The CCIS application uses sessions and application-registered users
and passwords for most access control. Apache realms are separately
used to limit access to functions for three special administrative
areas:

  (1) Agency search/admin (/admin/agency)
  (2) Resource Guide Administration (/admin/program)
  (3) User Administration (/admin/user)

Normal COSMOS users should NOT have access to these areas.

Set up Apache realm protection for those three administrative URLs. One
way to do this is with Location directives; for instance:

    <Location /admin/agency >
        ... (Apache directives to secure the realm)
    </Location>

    <Location /admin/program >
        ... (Apache directives to secure the realm)
    </Location>

    <Location /admin/user >
        ... (Apache directives to secure the realm)
    </Location>

- Configure application environment variables, for example:

    # Environment variables used by the COSMOS application,
    # see private/include/demo-test-setup-private.inc under "Application
    # setup items" in INSTALL.txt
    SetEnv CLIENT_GRP demo
    SetEnv CLIENT_MODE test     

- Configure Apache PHP settings for doc_root, open_basedir and include
path to allow access to the CCIS code, PHPlib, jpGraph, the TTF fonts
for jpGraph, and the include directory of the COSMOS public code tree.
For example:

    # PHP items
    php_admin_value doc_root "/cosmos-root/cosmos-distro/private"
    php_admin_value open_basedir ".:/cosmos-root/cosmos-distro/private:/cosmos-root/cosmos-distro/lib:/cosmos-root/phplib:/cosmos-root/jpgraph:/cosmos-root/fonts"
    php_admin_value include_path ".:/cosmos-root/cosmos-distro/private/include:/cosmos-root/cosmos-distro/lib:/cosmos-root/phplib:/cosmos-root/jpgraph"          
   php_admin_value register_globals Off

- Disallow certain files to be served directly to the web browser:

   # Don't allow '.inc' or '.ihtml' files directly via browser
   <LocationMatch "\.inc$">
     Order deny,allow
     Deny from all
   </LocationMatch>

   <LocationMatch "\.ihtml$">
     Order deny,allow
     Deny from all
   </LocationMatch>


Application logging:

COSMOS logs many actions via the standard Unix syslog, and is set up to
use the log facility local6. You will need to configure your system's
syslog to accept messages for 'local6'.  


Application setup items:

There are many control parameters that can be set for each of the two
sites- 'public' and 'private'. In some cases you will need to set the
same parameter for both sites, but many apply just to the private site.
Comments in the configuration files describe these, but some bear
special mention. Note that you will have to specify your own value for
every item in the distributed configuration files that has a value in
the form "SPECIFY_YOUR_*".


CLIENT_GRP and CLIENT_MODE setting effect on setup file name:

The setup file used by each site depends on the values specified by the
Apache environment variables CLIENT_GRP and CLIENT_MODE. The filenames
are effectively formatted:

    private/include/<CLIENT_GRP>-<CLIENT_MODE>-setup-private.inc

    public/include/<CLIENT_GRP>-<CLIENT_MODE>-setup-public.inc

...so if you use these settings in your Apache configuration:
        
   SetEnv CLIENT_GRP demo
   SetEnv CLIENT_MODE test     

...then the main file setup names should look like this:

    - public: 
        public/include/demo-test-setup-public.inc
        public/include/sys-setup-public.inc

    - private:
        private/include/demo-test-setup-private.inc
        private/include/sys-setup-private.inc

Note also that the function of the private site is modified by the use
of "test" or "dev" as the CLIENT_MODE (see below).


MySQL settings for both sites:

    - MySQL database name
    - MySQL user id for the read-only user
    - MySQL password for the read-only user


MySQL settings for private site only:

    - MySQL user id for the update user
    - MySQL password for the update user
    - MySQL user id for the admin user
    - MySQL password for the admin user


SSL certificate seal:

If you have a seal ID for a Verisign or other SSL certificate for the
private site running the COSMOS Client Information System, set your SSL
seal ID in demo-test-setup-private.inc (you can see how this value is
used in sys-setup-private.inc)- otherwise leave it set to an empty
string.


Logo:

A logo image URL is specified in both the include/demo-test-setup-*.inc
file and the include/flat-includes/demo/headfoot.inc file.


Salt for session ids:

In the sys-setup-private.inc file there are two places where "var
$magic =" should to be set to a random string of your choice that will
be used to salt the session IDs. There is another instance of this in
cosmos-distro/lib/session-cosmos.inc.


Super Admin setting:

The $aSuperAdmin array set in sys-setup-private.inc defines a list of
realm users (not database users) that have additional privileges when
changing agency capabilities. See private/admin/agency/agybit.inc for
specifics.


CLIENT_MODE setting effect on private site:

The production instance of the COSMOS sites should use 'prod' for the
value of the Apache environment variable CLIENT_MODE. If CLIENT_MODE is
set to 'test' or 'dev' COSMOS runs in test mode. In particular, the
private site function is modified as follows:

    - The COSMOS login screen identifies the site as a test service.

    - COSMOS referral emails are prominently labeled with a tag you can
      specify in your setup file (eg. demo-test-setup-private.inc), and
      emails reference the test system URL that you configured (also in
      your setup file.)


CONSENT_OTHER_AGY_ID:

There is a special "Other Agencies" agency that must be identified by
setting the CONSENT_OTHER_AGY_ID define to that agency_id in
private/include/demo-test-setup-private.inc. This is used in consent
processing. (See also "Agencies" under "Additional application setup
and usage".)


States, cities:

To change or add additional states (Virginia, North Carolina, ...) for
household addresses, etc., edit the $StateOpt array in
private/include/demo-test-setup-private.inc.

To modify the options populated in the address "City" dropdown boxes,
change or add 'location' items in the 'codes' table of the database.
There is no COSMOS-provided web interface to edit the codes table.
Edits or additions must be performed manually via the mysql
command-line tool or with a web-based MySQL administration tool such as
phpMyAdmin.

    code_types:
    
        location: data used to populate dropdown selections for cities 
        
        need: data used by need reporting section, and the referral
            section. 
               
        hhstart: data used to population "household history" update
            screen dropdowns.
        
        hhend: data used to population "household history" update screen
            dropdowns.
        
        relation: relationship of individual to head-of-household


Templates:

COSMOS uses the PHPLIB template system with a few conventions and
modifications:

- Filenames ending with .ihtml are template files. These files are used
to construct the HTML pages that are sent to a client's web browser.

- When templates are formatted for display the items enclosed in curly
braces, like '{ButtonAdmUpd}', are substituted with the value of a hash
variable array element by that name (eg. $hSomeVars[ButtonAdmUpd]).
This is typically something drawn from the database, and often wrapped
by the application in some HTML in addition to the HTML provided by the
template.

- You may customize the look of your pages by changing the HTML within
any .ihtml file.

- The .ihtml files may also contain references to other files that are
included as HTML. Any curly brace item that starts with '{INC_' draws
HTML from another file.

For an example, see cosmos-distro/public/search.ihtml and search.php.
The {INC_logo} reference will be replaced by the logo HTML in
cosmos-distro/public/includes/flat-includes/demo/headfoot.inc (this is
specified near the bottom of search.php).


Additional application setup and usage:


Agencies:

You will need to create agencies via the front page COSMOS link labeled
'Agency search/admin' (https://<cosmos-site>/admin/agency/).

On the agency admin modify screen, a superadmin has these checkbox
selections (see also 'Super Admin setting' above):

    Select where agency can appear:
        X Public Site       (If on, agency shows up on 'Online
                            Resource Guide' dropdown selection.)
        X Referral Dropdown (If on, agency can have clients referred
                            to them via the referral feature and
                            consent feature.)
        X User Admin        (If on, agency can contain COSMOS
                            application users, /admin/user/, and
                            agency shows up on user admin dropdown
                            list.)
        X Agency Admin      (If on, agency can be edited via the web
                            admin interface for agencies /admin/agency/)

        NOTE on Agency Admin setting: If you, as a SuperAdmin, unclick
        the 'Agency Admin' checkbox, then that agency will not be shown
        on the agency admin web interface screens. This may be set for
        agencies that you do not wish to be changed via the web
        interface. To return that agency to the agency admin web
        interface, edit the database table called 'agency', edit the
        intake_view field, set it to a value of 15, then go immediately
        to the agency admin interface and turn off the checkboxes you
        want.

Non-superadmins can only manipulate the 'Public Site' option.

Note that the special "Other Agencies" agency, which is identified by
the CONSENT_OTHER_AGY_ID define in
private/include/demo-test-setup-private.inc, should have the public
view bit turned off to prevent it from appearing in the Online Resource
Guide dropdown list.

         
Programs:

You will need to create programs via the front page COSMOS link labeled
'Resource Guide Administration' (https://<cosmos-site>/admin/program/).

Note that programs are associated with agencies, so the agencies should
be created first.


Services:

You will need to create services for your programs. There is no
COSMOS-provided facility to create or edit services. You must use tools
such as the mysql command-line interface or phpMyAdmin to manually add
services to the service table. See the demo data included in
cosmos_initial_demo_db.sql for examples. Services are associated with
programs, so the programs should be created first.


Application users:

You will need to create application users via the front page COSMOS
link labeled 'User Administration' (https://<cosmos-site>/admin/user/).
Users are associated with agencies, so the agencies should be created
first.

The cosmos_initial_demo_db.sql (referenced in the MySQL setup section
above) creates three COSMOS application users.
      
    user: demo1
    pass: pass4d1
    agency: agency1

    user: demo2
    pass: pass4d2
    agency: agency2

    user: demo3
    pass: pass4d3
    agency: agency3            


#################
# KNOWN ISSUES  #
#################

1- When updating an individual record, if an attempt is made to change
the social security number to one that duplicates a different
individual's SSN the system prints an obscure error message including
text in the form "System DB Error 1062: Duplicate entry '1-992-03-0005'
for key 2 query". Attempting to *add* a new individual with an SSN that
already exists works correctly; it prints a more user-friendly message.

2- HTML Instructions, (URL: /instructions), does not mention the
household history features.

3- There is no functionality for deletion of records; deletion must be
done manually, and with care to remove related records.

4- There is no service administration via web interface. The service
table entries must be entered manually in the database.

5- Although on the agency admin screen there is a checkbox for 'Public
Site', programs within that agency may still appear on the 'Online
Public Resource' public web site. However, the agency itself won't
appear in the agency search dropdown list.

6- Attempting to add a new COSMOS user with a duplicate username
results in a somewhat obscure error message: "MySQL Error: 1062
(Duplicate entry 'demo5' for key 2)".

7- COSMOS filtering of input data for cross site scripting (XSS) issues
may cause unexpected behavior when entering data. If you type in a
'less than' symbol ('<') in an input field, all characters following
that may be removed or modified by XSS filtering.

8- Two numeric fields only accept integer values: Household:Assets,
Individual:Monthly Income.
    - Entering a dollar sign '$' at the front of these fields results
    in a '0' amount.
    - Entering a comma results in chars after the comma being removed,
    eg 3,000 results in a value of 3.
    - Decimals are truncated, eg entering 300.98 results in 300

9- COSMOS will not accept dates before 01-01-1900 

10- As noted in the required PHP settings above, magic_quotes_gpc must
be on. Otherwise, SQL injection attacks may be possible.

11- Head of Household visibility:
    Clients who have been referred to you and granted consent are
    visible, but if the head of the household that person is in has NOT
    granted consent then the household head's SSN is listed as
    XXX-XX-XXXX. This is the intended behavior.

    When the household head's SSN is listed as XXX-XX-XXXX, clicking
    the button labeled "View Head of Household" on the Household detail
    screen will result in the message: 'No records matched your search
    criteria'.

    The head of household is invisible to you if you don't have
    consent.

12- Referral Emails: Emails notifying referred-to agencies (referral
emails) are sent before the consent has been created.  However, a
referred-to agency cannot view an individual's information if the
referring agency has not completed a consent. The user perspective to
date has been that the current procedure was acceptable, so long as the
referred-to agency cannot view the individual if the consent has not
been completed.

13- Share Additional Information: Individuals have the option of
allowing agencies to "share additional information received after this
consent is signed." Individuals may choose "Yes" or "No". "Yes" means
that an individual has given consent for an agency to view any
information that is updated after the consent is signed. Currently the
system does not block access to the individual's information if it
changes and the individual chose "No".

14- Computerized Data: Individuals grant agencies access to three
information types: written, in meetings or by phone, and computerized
data.  All information entered into the system is "computerized". 
Computerized data should always be selected for referrals made through
the Client Information System. Currently no warning is issued if
computerized data is not selected.

15- Consent Revoked Problem: Agency A performs an intake on individual
X and gives consent to Agency B.  Agency B adds individual Y to the
household.  If individual X revokes consent for Agency B, or the
consent expires, Agency B can no longer view individual Y's household.

16- Referred-to Agency Can Change Individual Information: Agency A
performs an intake on individual X and refers individual X to Agency
B.  Individual X grants consent for Agency B to view his information.
Agency B can then also update individual X's information, although they
cannot modify individual X's consent form.

17- Moving Individual Removes Consent for Household View: An agency
performs an intake on an individual and grants consent for a
household.  When the individual is moved from the original household
into a new household, the consent is not updated. The result is that
agencies that had consent to view the original household cannot view
the new household.

18- Simultaneous Updates to Household History: It is possible for more
than one user to update Individual Household History records
simultaneously, leading to invalid data being stored in the database.
Although this is not likely to become an issue if the system is used on
a small-scale basis, and specific households are only updated by a
single user, a locking mechanism should be implemented to prevent this
possibility.

19- Services of Other Agencies Visible: When Agency A refers an
individual to Agency B, which means the individual has granted consent
to Agency B, then users in Agency B can see not only the individual's
demographic data, but also the history of services provided by any
agency to that individual (including agency A as well as any other
agency to which the individual has been referred). This may raise
privacy issues depending on the agencies involved and the individual's
understanding that all information from all agencies for past and
future services is covered by the consent.

--------------------------------------------------------------------