README

Download
--------

[dl]: git://github.com/mcr/can-o-pg.git 


Introduction
------------

Sets up a new installation of the postgres data files and configuration.
Postgres can run as the user that installs these files.  Postgres will
be configured to use sockets rather than network for communications.

This is useful for developer environments or for applications which want
the exclusive use of the database (eg, ledgersmb).  Also useful for running
postgres-backed programs in environments where you don't have root.

This set of scripts[0] will set up a postgres configuration and runtime directory
under the current directory.  It will use the system executables.

The scripts will use bootstrap.sql.in to do some prep on the DB:
create a couple of databases and users with default passwords.
The scripts will convert bootstrap.sql.in into bootstrap.sql, and
then run bootstrap.sql in the psql environment.


For historical reasons, the scripts expect that the can-o-pg directory
will be in vendor/plugins/can-o-pg, and the Makefile will be beside vendor
(actually it's a link to vendor/plugins/can-o-pg).  That's because
can-o-pg was developed in a Rails environment.  However, it is not
required to run in that directory structure.  In the Makefile at the
top, change SCRIPTDIR to . (dot) if you do not want to put it in
vendor/plugins/can-o-pg.


[0] The scripts are collected together into a Makefile.  A few auxilliary
scripts are separated out into files (findpgsql.sh, portnum.sh, etc) but
are called from the Makefile.

To run the scriptlets in the Makefile, give the make command along with
the "target" name:

    make showconfig


will run the scriptlet associated with the "showconfig" target in the
makefile.

    showconfig:
        @echo POSTBIN="${POSTBIN}"
        @echo APPNAME="${APPNAME}"
        @echo DBPATH="${DBPATH}"
        @echo DBPASSWORD="${DBPASSWORD}"
        @echo SCRIPTDIR="${SCRIPTDIR}"
        @echo TOP="${TOP}"
        @echo APACHE2_MODDIR="${APACHE2_MODDIR}"
        @echo WEBSERVER="${WEBSERVER}"
        @echo MIMETYPES="${MIMETYPES}"
        @echo PHP5_MODDIR="${PHP5_MODDIR}"
        @echo DATABASE="${DATABASE}"
        @echo SYSTEMPORT="${SYSTEMPORT}"
        @echo SYSTEMURL="${SYSTEMURL}"

In case you want to edit the Makefile, note that makefiles use tabs (not spaces)
for delimiting the beginning of the lines for the scriptlets.


CONFIGURATION
=============

run "make showconfig" to see what the settings are, you should see something
like: 

        POSTBIN=/usr/lib/postgresql/8.3/bin
        APPNAME=chapter13
        DBPATH=/corp/projects/credil/nv/chapter13/run
        DBPASSWORD=baesheDaic5OhGh2
        SCRIPTDIR=vendor/plugins/can-o-pg
        TOP=/corp/projects/credil/nv/chapter13
        APACHE2_MODDIR=/usr/lib/apache2/modules
        WEBSERVER=/usr/sbin/apache2
        MIMETYPES=/etc/mime.types
        PHP5_MODDIR=/usr/lib/apache2/modules


If you need to override certain of these values (see the list below of overrideable
items), you can use the file "can-o-pg.settings" at the top level.  It is a makefile
format file that will be included into the Makefile at runtime if it exists.

Overrideable settings:
    DBPASSWORD
    DBPATH
    DBCLUSTER
    DATABASE

You can create the file with "touch can-o-pg.settings" or by redirecting the
make showconfig output to a file:

    make showconfig > can-o-pg.settings

Be sure to remove the items that are not overrideable.
If you want to change one of the other items, it must be done directly in
the Makefile.



APACHE
======

Similarly, this script can run apache as a regular user (rather than root) for
development environments.

If you need Apache (and you do if you are doing PHP5 work), then just run
"make apache" and an apache configuration will be created in run, and a copy
of Apache will be started.   It will be started on a port number equal to 8000
plus your uid.  This choice is stable per user, but permits multiple users 
to work on a multiuser machine (this is common if you have windows programmers 
using putty to a linux machine).

PHPPGADMIN
==========

No doubt you will need to tweak the database by hand at times.
phppgadmin is a very good tool. If you have a copy in /usr/share/phppgadmin,
it will be linked into the apache config at /phppgadmin.  It is connected
to the database by Unix domain socket.  You can use the roles created
by the bootstrap.sql, such as application_development.


USING IT
========

You will find a Makefile at the top-level.

You'll want to edit bootstrap.sql.in eventually.

Open up the can-o-pg.settings, and change APPNAME= if the name of the current
directory is wrong.

But, for now, just do:
        make


for Rails apps, you can:
        cp database.yml config/database.yml

("make server" will do this for you)

EXTRAS
======
make psql                - starts psql in the current database context.
make INPUTFILE=foo load  - starts psql with "foo" on command line 
                           populate the database.
make apache
make apachestop         - stop apache
make stop               - shutdown database
make                    - start the DB again.  Careful, if you have fiddled too much
                          with the config/runtime files, it will wipe out your DB and
                          re-create from scratch.  You'll have to read the Makefile
                          dependencies to figure out when this will happen.
                          It might be nice to make a new rule just for starting the
                          executables so there is no risk of losing data, but that's
                          not there at the moment.
make showconfig         - show settings