Chapter 2. Administration Guide

The Administration Guide is meant for system administrators that will be installing or managing the NorthStar system. If your interested in how to use NorthStar then please refer to the User Guide.

2.1. Installation

Welcome to the Installation guide. Hopefully this guide will walk you through the installation of the NorthStar system in the easiet and least time consuming way. If you have any problems during the install please refer to the Support section to see information on how to get help with your problem.

2.1.1. Choosing an Installation Directory

The NorthStar package needs to be installed in a directory that is accessable by your web server. The default location is /usr/NorthStar however the following directories may also be used:

  • /usr/local/NorthStar

  • /opt/NorthStar

If you would like to install into another directory the you will have to edit the NorthStar.cgi file by hand and add your directory to the @searchdir array around line 21. For the purpose of this document we will assume the installation directory is /usr/NorthStar

2.1.2. Downloading and Unpacking NorthStar

Currently you can download the latest version from the NorthStar website located at http://www.brownkid.net/NorthStar/. To download the latest version click the Download link and pick the version number that you would like to download.

After downloading the file execute the following commands to unpack the archive:

$ cd /usr
$ gzip -dc NorthStar-x-x.tar.gz | tar -xvf -
			
You should now have the NorthStar package untared and ready to install.

2.1.3. Configuring NorthStar

Now that we have unpacked the NorthStar system were ready to set the parameters that NorthStar will need to run. This configuration is handled by the file NorthStar.conf in your /usr/NorthStar directory. The file format should be pretty straightforward and comments are included in the NorthStar.conf.sample file to explain what each configuration item means. To edit the configuration file using vi enter the following command:

$ vi /usr/NorthStar/NorthStar.conf
			
Once you have edited the configuration file to meet your needs save it and we'll continue to setting up the database schema for NorthStar

2.1.4. Database Setup

We will now configure your PostgreSQL Database server with the database structure needed to run the NorthStar system. This section assumes you have PostgreSQL installed and running, have a working knowledge of the PostgreSQL database system, and also have permission to create a new user and database.

Provided that you meet all the above conditions you can create the initial database structure by using the SQL command file named NorthStar.sql. This file is located in /usr/NorthStar.

To create the database users and structure execute the following command:

** WARNING: If you are upgrading from a previous version of NorthStar please goto the 'Upgrade Instructions' section for database update procedures

$ /path/to/psql template1 < /usr/NorthStar/NorthStar.sql
			

Additionally you probably want to create entries in pg_hba.conf to reference your host and assign a password for database access. If a password is assigned be sure to put the password in the NorthStar.cgi file.

2.1.5. Setting up your Webserver

NorthStar currently needs a web server that can execute CGI programs and also supports following symlinks in a configured directory. This section is specific to the Apache web server, however, configuring for another web server should not be very hard.

2.1.5.1. Installing with Symbolic Links

First, we need create a directory under your web root to hold the links to the NorthStar scripts and the html templates. In this example /var/www/htdocs/ is used as our webroot. You should change this in the following commands to your local webroot. To create the directory and symlinks execute the following commands:

$ mkdir /var/www/htdocs/NorthStar
$ ln -s /usr/NorthStar/NorthStar.cgi 	/var/www/htdocs/NorthStar/NorthStar.cgi
$ ln -s /usr/NorthStar/html /var/www/htdocs/NorthStar/html
				
Now that the needed links have been created we need to configure Apache to execute CGI programs and follow symbolic links in the NorthStar directory under your web root. To do this add a section to your httpd.conf file that looks like this:
										
<Directory /var/www/htdocs/NorthStar>
	Options ExecCGI FollowSymLinks
</Directory>
					
					
				

Your webserver should now be configured to run NorthStar. To complete the process restart the server by entering the command /path/to/apachectl restart

2.1.5.2. Installing without Symbolic Links

Installing without symlinks is fairly easy. We need to create a directory under your webroot called NorthStar to hold the main program files and HTML templates. In this example /var/www/htdocs/ is our web root.

To create the NorthStar directory and copy the needed files execute the following commands:

$ mkdir /var/www/htdocs/NorthStar
$ cp -R /usr/NorthStar/NorthStar.cgi /var/www/htdocs/NorthStar
$ cp -R /usr/NorthStar/html /var/www/htdocs/NorthStar

				

Be sure to set the 'HTMLDir' option in the NorthStar.conf file to the directory that the HTML files are in. In this example you would set HTMLDir to '/var/www/htdocs/NorthStar/html'.

Now that the needed files have been copied we need to configure Apache to execute CGI programs in the NorthStar directory under your web root. To do this add a section to your httpd.conf file that looks like this:

										
<Directory /var/www/htdocs/NorthStar>
	Options ExecCGI
</Directory>
					
					
				

Your webserver should now be configured to run NorthStar. To complete the process restart the server by entering the command /path/to/apachectl restart

2.1.6. Database Update Procedures

If you are upgrading from a previous version of NorthStar then you may need to update the database schema in your existing database to run the new version. Before updating your existing database you should probably backup the information in it just in case something goes wrong. To do this run the command /path/to/pg_dump northstar > northstar.backup. If you need to update your database schema a file named update_x.x.[sql|pl] (where x.x will be the version number of NorthStar that you are trying to install) will be in your /usr/NorthStar directory. If the file ends in a .sql extension the to apply the update just run these commands:

$ /path/to/psql northstar < /usr/NorthStar/update_x.x.sql
			
If the file ends with a .pl extension then you run the file as a Perl script. To do this execute these commands:
$ perl /usr/NorthStar/update_x.x.pl
			

2.1.7. See if it runs

Now that you have completed the install steps you should open up your favorite web browser and enter the URL to the NorthStar script. Most likely this will look something like http://www.yourserver.com/NorthStar/NorthStar.cgi

You should be presented with a login page. If this is a new installation of NorthStar then you should login with the username admin and password admin. If you have any problems please check your error logs for more information and if need see the 'Support' section to find out how to get help.

2.1.8. Change the Admin Password

The last thing to do is to change the admin password to something a little more secure then the default of admin. To do this login to NorthStar as the admin user (you should have already done this) and click the "Change Password" link in the leftmost frame. You should be presented with a page asking you to enter the new password and verify it. After entering the new password click the "Change Password" button and there ya go.. your admin password is changed. You should now click the "Logout" link the in the leftmost menu and login with your new password to make sure everything worked ok.