skyBuilders timeLines GNU/Linux/Apache/PHP/PostgreSQL Installation HOWTO

skyBuilders timeLines GNU/Linux/Apache/PHP/PostgreSQL Installation HOWTO

Interesting links (in no particular order):
RedHat
The GNU Project
The Apache Software Foundation
The Comprehensive Perl Archive Network
PHP Hypertext Preprocessor (documentation)
PostgreSQL (documentation)
Open Secure Shell
The National Institute of Standards and Technology
WebMin

This is the process for configuring a new RedHat 7.3/8.0 installation to become a skyBox capable of running (and developing) skyBuilders timeLines. No other distributions have been tested as of this date, but there are no known issues to prevent the Apache/PHP/PostgreSQL version of timeLines from running in any Linux or other Unix-like environment. In order to be capable of this, there are a few required services and utilities:

httpd service with middleware: Apache mod_perl and mod_php
RDBMS: PostgreSQL
GUI for maintenance and development: XFree86, Gnome
Editing and Network Utilities: the GNU Project system of software tools

Install RedHat 7.3 or 8.0
See the RedHat site for full distribution and documentation.
Unless otherwise noted, the following commands expect to be run as root.

Add crontab for NIST clock synchronization
(add other things like updating the root hints file and the file db later)
    # cd /root
    # mkdir scripts
    # cd scripts
Download http://jesse.skybuilders.com/scratch/other/misc_linux/miscScripts.tar
    # tar -xvf miscScripts.tar
    # crontab clockSynch.cron
To see current settings, # crontab -l

Enable ssh for all users who will require remote access.
SSH lives in /etc/ssh
Edit sshd_config
Use the PermitRootLogin instruction to restrict or allow remote root access.
Go to the end of the file
After the last line, add a line that reads "AllowUsers" followed by a tab followed by a space-delimited list of usernames to allow
Test login

There is an upgrade for openSSH (possibly available from the website), which patches a security hole to which we are not, under our current settings, vulnerable. The ideal version would be 0.9.6e
To report current version:
# rpm -q <rpmname>
To upgrade with verbose and progress bar:
# rpm -Uvh <rpmname>

Locate Apache httpd

/etc/httpd is the program directory
/etc/httpd/conf/httpd.conf is the configuration file
/var/www/html is the wwwroot/home directory for the server
# service httpd start/restart/stop/status can be used to control the service

Set httpd to start on boot
To check the current setting:
# chkconfig httpd --list
To set the service to start on boot:
# chkconfig httpd --level 3456 on

Test http service
Open any browser to the fully qualified domain name or the IP Address of the machine
The index page should be the Apache test page
If there is an error, then the httpd service is not running. To start it:
# service httpd start
service should reply OK. Retest.

Test PHP
Change directory to the web root (in this case '/var/www/html/' by default)
Create a file called test.php and put into it one line: '<?php phpinfo(); ?>'
Direct a browser at the file and check the output. It should display a series of tables describing the machine and its php installation (see the php.net docs page on phpInfo() for more info).

Make appropriate changes to php.ini
php.ini is in /etc
Here are the lines to look for that show their default values, each followed by the line that should replace it (the preferred method is to comment out the default line to preserve it, and put the new setting on the following line - the comment character is a semicolon ';'):

memory_limit = 8M
memory_limit = 16M
magic_quotes_gpc = On
magic_quotes_gpc = Off
file_uploads = Off
file_uploads = On
[This may default to 'On' in other versions of PHP]
SMTP = localhost
; SMTP = localhost
sendmail_from = me@localhost.com
; sendmail_from = me@localhost.com
; sendmail_path =
sendmail_path = <path to sendmail>
[in this case "/usr/sbin/sendmail -t -i"]

Set postgresql to start on boot
To check the current setting:
# chkconfig postgresql --list
To set the service to start on boot:
# chkconfig postgresql --level 3456 on

Test postgresql
Check whether postgresql is running:
# service postgresql status
If service replies that postgresql is stopped, then:
# service postgresql start
service should reply OK

postgresql helpful hints
This section is just a few helpful pointers and links about how to handle you postgres installation. Actual instruction begins again in the next section (Enable proper logging for postgresql).
PostgreSQL configuration is in /var/lib/pgsql/data/postgresql.conf
Host Based Access configuration file is in /var/lib/pgsql/data/pg_hba.conf
To make a database (which will be owned by the operating system user who issues the command):
bash-2.05b$ createdb <dbname>
All user and db management can be done through the PostgreSQL interactive terminal (which accepts both SQL statements and Postgres metacommands) called psql (man psql for reference):
bash-2.05b$ psql <dbname>
which takes you to a prompt which looks like:
<dbname>=#
To add/manage users:
PGSQL User Management
To create users:
<dbname>=# CREATE USER <username>
Every db must be VACUUMed at least once every billion transactions with the vacuum command in psql (or risk catastrophic data loss). See Routine Vacuuming.
A few useful tools.
To list all postgresql users:
<dbname>=> SELECT * FROM pg_user;
To list all postgresql databases:
<dbname>=> SELECT * FROM pg_database;
To find out the currently selected database, look at the name in the prompt:
<dbname>=>

Enable proper logging for postgresql
Edit the file /etc/init.d/postgresql
Find the line that reads:
   su -l postgres -s /bin/sh -c "/usr/bin/pg_ctl -D #PGDATA -p /usr/bin/postmaster start > /dev/null 2>&1" < /dev/null
Edit the line to read (changes marked in bold, note double greater than after 'start'):
   su -l postgres -s /bin/sh -c "/usr/bin/pg_ctl -D #PGDATA -p /usr/bin/postmaster -o '-i' start >> /var/log/pgsql 2>&1" < /dev/null
Save the file
Restart postgresql:
    # service postgresql restart
service should reply OK

Configure pgsql users and databases
First, the user called 'postgres', who is the superuser for the postgresql service, must have a new, secure password assigned both in the operating system and in the postgresql service. Next, a file called 'admins' must be created to indicate that the postgres user can connect to any database with a password challenge. Then, other users must be added to pgsql. One user should be defined for each timeLines installation on the machine. Finally, the new database(s) for the timeLines installation(s) must be created.

Create the postgresql admin user and set permissions for postgresql users:

As root, change the password for user postgres in the operating system by using the command passwd:
# passwd postgres
This command will now challenge you for the new secure database admin password which should be carefully kept track of, with the usual precautions of length, and a mix of letters, numbers, and symbols. This password will be needed again in step 4.
Run a shell as the postgres user:
# su postgres
which takes you to a prompt which looks something like:
bash-2.05b$
Connect to template1 (postgresl's template database) as user postgres by using the command psql, which opens the PostgreSQL interactive terminal. (Whenever in the terminal, be sure to expect confirmations of any action; a null response is a sure sign of no action performed.)
bash-2.05b$ psql template1
Change the password for user 'postgres' in the postgresql service by using the 'ALTER USER' command. Be sure to surround the password with single quotes/apostrophes as shown. The terminal should confirm by replying 'ALTER USER'. When using the following example, <newpassword> should be replaced with the new, secure password assigned in step 1. above. (Note that unlike the passwd command above, 'ALTER USER' will not automatically conceal the password as it is being typed. Be sure to enter it only in a secure environment.)
template1=# ALTER USER postgres WITH PASSWORD '<newpassword>';
Exit psql.
template1=# \q
Exit postgres user session.
bash-2.05b$ exit
Initially, PostgreSQL allows anyone from the local machine to connect to the databases without a password challenge, so as to allow the administrator to set the password for the postgres user. Once that has been done, access to the databases must be securely restricted. This is controlled from the file /var/lib/pgsql/data/pg_hba.conf. Open this file and make the following edits:
- Make two copies of line 221 at the bottom of the file. Uncomment the lines by deleting the pound sign '#' from the front of both lines (the '#' is a comment character, which tells the configuration engine to ignore that instruction). In the second copy, edit the word 'sameuser' to say 'template1'. The first copy will allow any user to connect to a databse with the same name as their username. The second, edited copy will allow all users to be able to connect to the template database in order to create their own.
- Copy line 222 to the bottom of the file, uncommenting it by deleting the '#'. This will allow the postgres user to connect to any database.
- Copy line 190 to the bottom of the file and uncomment it. Edit the word 'template1' to say 'all', and edit the ip address in this line to match the machine's ip address. This will allow remote connections.
- Comment out line 250 by putting a '#' at the front of it.
In the same directory /var/lib/pgsql/data/, create a file called 'admins'. Write into this file one word, the name of the database admin user, 'postgres' (excluding the single quotes/apostrophes in this case). These configuration changes will only be applied the next time the service is restarted.
Restart the postgresql service.
# service postgresql restart

Create new users and databases:

Run a shell as the user postgres to do some user management.
   # su postgres
Create a new database user. The name of this new user should correspond to the fully qualified domain name of the site that the database will be supporting, subtituting underscores for the dots. For example, if your domain name is "www.example.tld", the corresponding user name should be "www_example_tld". This should also be the name of the database. Permissioning restricts users other than the admin user "postgres" to connect only to "template1" and the database with the same name as the user.
To make users (outside psql) as user postgres:
   bash-2.05a$ createuser <options> <username>
The options that should be used are:
-d = allowed to create databases
-P = prompt for a password
-A = not allowed to create users
Using our example:
   bash-2.05a$ createuser -d -P -A www_example_tld
The password for the new user will now be prompted for. This should be another equally secure password, preferably different from the postgres user password, especially if there will be multiple timeLines installations on this machine. This password will be required by the timeLines installation script later in order to initialize the database and enable the application.
The password will be challenged for a second time for confirmation.
Finally the postgres admin password will be asked for, to authorize the new user.
createuser should reply CREATE USER
The new user has now been created!
(man createuser for details, dropuser to delete users, and ALTER USER from inside psql to change settings for a user)
Exit the postgres shell to get back out to the root shell.
Connect to template1 as the new database user. You will be challanged for the new user's password. (Notice that the terminal prompt ends with a ">" rather than a "#", to show that you are not a superuser (postgres).)
# psql template1 <username>
Create the databse for this user, named with the new user's username. Ownership of the new database is automatically assigned to its creator. The terminal should respond "CREATE DATABASE".
template1=# CREATE DATABASE <username>;
Using our example:
template1=# CREATE DATABASE www_example_tld;
Connect to the new database. This will confirm its existence. The terminal should respond "You are now connected to database <dbname>."
template1=> \c <dbname>;
The database for this timeLines installation has now been created!
Exit the psql terminal to return to the root shell:
template1=> \q
Repeat user and database creation for each timeLines installation on the machine.
PostgreSQL users and databases are now configured.

Install the timeLines application

Create a directory alongside the default web root (in this case "/var/www/html/") using the fully qualified domain name of the new site (in our example "/var/www/www.example.tld"). Move into the new directory and make another directory there called "timelines". Move into the timelines directory.
Download the installation archive file from downloads.skybuilders.com.
Decompress the installation archive into the the new timelines directory. All necessary application server pages, directories, and image files will now be in place.
Permissions must be set on the application directory. Create a group called "skyApp", if it has not yet been created. This will be the group that gives anonymous and administrator access to all timelines application sites.
# /usr/sbin/groupadd skyApp
Add users to this group. The apache user (in this case "apache") must be added so that requests to the web server will have permission to operate on the site. Other users that may need to be added to this group are any non-root administrators of the machine or the site, or any users who require ftp or sftp access (though any users who require different permissioning from the web users should be permissioned separately).
# /usr/sbin/usermod -G skyApp apache
# /usr/sbin/usermod -G skyApp <username>
Change the group setting for the site directory (recursively, for all the files and directories below it).
# cd /var/www
# chown -R :skyApp www.example.tld
Set permissions for the site directory (recursively, for all the files and directories below it).
# chmod -R 775 www.example.tld
Restart the web server httpd.
# service httpd restart

Enable virtual servers under apache
Open the file /etc/httpd/conf/httpd.conf for editing
Add these lines to the virtual servers section (substituting the appropriate machine name and domain name), with an extra VirtualHost section for each timeLines installation:

   NameVirtualHost *

   <VirtualHost *>
     ServerName www.example.tld
     DocumentRoot /var/www/html
     AddType application/x-httpd-php .php .php4 .php3 .phtml .html .xml .xsd .rdf .rdfs
   </VirtualHost>

Note: Apache 2.0.40-8 (RedHat 8.0 distribution) does not currently support the IP wildcard, '*' in the example above. This version requires IP number(s) to entered directly into the httpd.conf entries for NameVirtualHost and VirtualHost entries.

Save the file
Restart the web server httpd.
   # service httpd restart

Run the timeLines installation script
This script will build the new database's schema and populate it with initial data. Open a timeLines-compatible browser (Mozilla > 1.1, Netscape > 4.0, Internet Explorer > 4) and navigate to the following URL (where <domain name> is the domain name of your new site):
http://<domain name>/timelines/Install.html
timeLines will now challenge for the database password for the new site (as set in the section Configure pgsql users and databases). Initialization should take around two minutes.

skyBuilders timeLines installation should now be complete!
Please report any bugs at our interactive Bug Report. Thank you.