newbie notes 1: getting started

["D. Hugh Redelmeier" <..hidden..>]

Why am I, a newbie, posting my experiences to the developers' list?
Because I'm only this ignorant once, ignorant enough to run into
problems that the experienced among you cannot even imagine.

Oscar Wilde said "Ignorance is like a delicate flower: touch it and
the bloom is gone."

This long message is meant to be constructive.  Please don't take it
as whining.  I'm appreciate all the effort that the creators have put
into this.

================

Starting out: I want to use Ubuntu 8.04 (LTS is a Good Thing) but I
happen to be using 8.10 for a dry run.

I'm really thankful that Elizabeth Bevilacqua has produced a LedgerSMB
.deb file that appears to work on 8.10.  When I last started on this
project, the .deb file would not work because it wanted PostgreSQL
before 8.3 and Ubuntu would not oblige.

==> the download page should say what target systems the .deb is
    intended to work on.  All it says is "Platform-independent"
    (which probably means that it works on i386, AMD64, SPARC, etc.).

    I just assumed that that the .deb would work on my Ubuntu 8.10
    but the lack of certainty was a problem.

    The same criticism applies to the .rpm: on which distros will it
    work?

I don't know how to deal with dependencies in a .deb.  I may not be
alone.  I used dpkg -i to install the package.  I got a lot of
complaints.  "apt-get -f install" seemed to fix things up.

I need a howto to guide me.  Google leads me to
  http://ubuntuforums.org/showthread.php?t=311029
Unfortunately, it is obsolete.

I find out (too late) about README.Debian (from INSTALL).

==> Perhaps some big "START HERE" sign is needed.  Perhaps there was
    one that I missed.

==> it would be really nice if the .deb files were contributed to a
    Ubuntu repository.  That way dependencies would get handled by the
    machinery of apt-get or synaptic.

While writing this, I came across
  http://ledgersmb.frauerpower.com/index.php/Ledgersmb_1.2_Installation
Unfortunately it seems outdated.

Maintaining documentation "out-of-tree" invites synchronization
problems.  I suggest focusing on documentation like INSTALL and
README.Debian and exposing them for separate download so that they can
be read before installation.

================

I installed LedgerSMB.  I may have gotten it wrong since I followed
two different recipes (the Ubuntu Forums article and the
README.Debian).

I could not log into LedgerSMB.  I got the error described in INSTALL:
 Error: "No GlobalDBH Configured or Could not Connect"
Unfortunately, none of the hints in INSTALL worked for me.  Nor other
fixes that google turned up.  Nor the help from jm on #ledgersmb.

One thing in particular in INSTALL left me wondering.  

I think that I found the problem by reading code in
  /usr/share/ledgersmb/LedgerSMB/Sysconfig.pm
Line 125 says:
    my $dbconnect = "dbi:Pg:dbname=$globalDBname host=$globalDBhost
                port=$globalDBport user=$globalDBUserName
                password=$globalDBPassword";    # for easier debugging
It looks to me as if whitespace is a delimiter and there is no quoting
of the password.  My password contained a space.

Note: PostgreSQL had no problem with a space in a password.  The "psql
-u" test mentioned in INSTALL worked fine.  But LedgerSMB didn't.

This paragraph in INSTALL left me puzzled:
    The full line should then be something like:

    DBConnect: dbi:Pg:dbname=ledgersmb;host=localhost;port=5432

Where is this line supposed to be?  Context suggests that it should be
in ledgersmb.conf but there is nothing like that.  Is this left over
from an old version?

==> rules for valid password characters should be made explicit.
    (The FAQ mentions that = and & should be avoided.)

==> limitations on passwords characters (and form in general) should
    be enforced early -- when it is easy to fix the password.

    The symptom(s) of a malformed password should be an explicit
    diagnostic to that effect, not just a non-specific failure to log
    in.

Being a newbie, I don't know how to change the password on a
PostgreSQL "user".  I resorted to deleting all the PostgreSQL things
(users etc.) that I had created and starting again.  Is there a good
cheat-sheet for PostgreSQL?  All I want to know is enough to use
LedgerSMB.

When I recreated things, I used the same password everywhere.  I think
that there are different passwords for different purposes, but I was
not confident which password was needed in each context.

==> for each use of a password, make it clear which password is to be
    used.  (This may already be clear and that I'm being confused by
    my own creeping uncertainty.)

================

I have little experience with Apache and PostgreSQL.  I'm using each
just to support LedgerSMB.  It would be handy if the LedgerSMB
documentation helped me with these other systems just enough to
satisfy LedgerSMB's requirements.  There is some attempt at this, but
my ignorance discovers gaps.  For example, a clear cookbook for
authentication matters (along with clear description of the
implications of choices) would be good.  A pointer into specific parts
of these other projects' documentation would be quite reasonable.

As an example, I'm not 100% confident of the new lines I've added to
  /etc/postgresql/8.3/main/pg_hba.conf

README.Deb mentions the pg_hba.conf in step 6 but isn't explicit about
what the required line looks like or where to place it.

================

Now I get a login screen from LedgerSMB!  That means that LedgerSMB
can log into PostgreSQL.  But I don't yet know what to do with it.
Tentatively, I enter the name "admin" and my universal password.  I
get this page:

    Error!
    LedgerSMB/User.pm:199: FATAL: database "host=localhost" does not exist

What does that mean?  This diagnostic looks like it is meant for an
implementer, not a user (hey, I've been accused of creating similar
messages).

==> if possible, messages should be meaningful to users and
    developers.

This is the event that made me stop whacking at problems and write up
my experiences.

I hope that some of you find this message useful.