[OPEN-ILS-DEV] Some comments & Suggestions for the EG 2.1.0 README as exists on the web site

[Dan Scott]

Hi Wolf:

On Mon, Nov 07, 2011 at 03:46:49PM -0500, Wolf Halton wrote:
> http://www.evergreen-ils.org/documentation/install/README_2_1_0.html
> This is a set of suggestions for the README.
> Line 7 is a specific wish-list item but the rest is just a clean-up of some
> good work by dbs and a lot of others here.
> 
> =====================
> 
> Install Prerequisites Section:
>     Could have a link to the opensrf install instructions.  Without that
> and without an opensrf user the rest of the instructions are difficult.

Step 1 of "Installing prerequisites" is "Begin by installing the most
recent version of OpenSRF (2.0 or later). You can download OpenSRF
releases from http://evergreen-ils.org/opensrf.php" which seems pretty
clear, and avoids release linkage issues (for example, if OpenSRF-next
is released after the README for this particular Evergreen release is
released, then the README for this Evergreen release would be pointing
to the instructions for an out-of-date OpenSRF release).

>     It would be cool if the most recent opensrf and evergreen tarballs
> could br aliased to opensrf-current.tar.gz and
> Evergreen-ils-current.tar.gz.  This would make the installs simpler.

I'll leave that as an open question for Ben and Anoop and anyone else
handling the Web site; this would probably be easier if we were only
maintaining a single supported release at a time. Also, if -current
results in a redirect to (say) -2.0.4 then it doesn't really solve the
"untar" command problem below.
> 
>     At any rate, there needs to be some detail about
>     [code]
>     wget http://www.evergreen-ils.org/downloads/Evergreen-ILS-2.1.0a.tar.gz
>     tar xzf Evergreen-ILS-2.1.0a.tar.gz
>     [/code]
>     Remembering that the average person installing may well be using ssh to
> a server without a gui for searching around, and judging from the list
> traffic, I may not be the least-experienced person attempting to install
> this product-suite.

Generally, if you're using SSH then you have that running in a terminal
window, and have other windows available to run browsers, etc. That
said, this is a repeat of a request that Yamil and Martha brought up
earlier, so I've gone ahead to add these steps. Aside: we need to add
"update the version references in the README" to the release-cutting
steps for Evergreen.

> "Configure OpenSRF for the Evergreen application" Section
>     Before copying the new config files in, make a backup of your effective
> config files.
>     [code]
>     cp /openils/conf/opensrf_core.xml /openils/conf/opensrf_core.xml.bak
>     cp /openils/conf/opensrf.xml /openils/conf/opensrf.xml.bak
>     [/code]
>     This may help if you forgot to write down the ejabberd user passwords.

Good suggestion; I simply added the "-b" flag to the "cp" command to
automatically create backups and added a note about that.

> "Creating the Evergreen database" Section
>     The very first sentence here says, "By default, the Makefile.install
> prerequisite installer does not install the PostgreSQL 9.0 database server
> required by every Evergreen system;.." This is untrue.  The
> Makefile.install installs postgresql-9.0 by default.  What it doesn't do is

The Makefile.install installs the postgresql-client-9.0 package by
default. It doesn't install the PostgreSQL 9.0 server by default, at
least not on a clean system.

> purge the postgresql-8.4 which is using the default postgresql port, 5432.

The PostgreSQL 8.4 server won't exist on a clean install (unless, say,
you chose to install a database server when you were installing the 
OS).

For the following bits, the Downloads page has links to the "upgrade
instructions" wiki page at
http://evergreen-ils.org/dokuwiki/doku.php?id=upgrading:evergreen:2.0.10_to_2.1.0
I'm pretty sure I don't want to mix upgrade info into install
instructions. There's certainly room for an UPGRADING file to complement
the README, though, if anyone is feeling frisky.

> To get the next step to work, there has to be 2 things handled.
>     1.) If you have an existing 8.4 evergreen database, there must be a
> link to the "HOW-TO migrate your postgresql-8.4 database to 9.0" page and
>     2.) A HOW-TO about purging the postgresql database and configuring your
> postgresql-9.0 database.  This would go in just above the "For a standalone
> PostgreSQL server, install the following Perl modules as the root Linux
> account:" instruction.
> 
>     --To purge the PostgreSQL-8.4 Installation--
>     1.) Make sure you do not have to migrate your database - if you do, go
> to
> http://evergreen-ils.org/dokuwiki/doku.php?do=subscribe&id=upgrading_postgresql_8-4_to_postgresql_9.0_on_ubuntu_10.04(or
> whatever official HOW-TO is more current)
>     2.) As the root user On Ubuntu or Debian:
>     [code]
>     aptitude purge postgresql-8.4 postgresql-contrib-8.4
>     [/code]
>     3.) As root user on a Debian or Ubuntu machine, edit the following file
> to point to the default network port:
>     [code]
>     vi /etc/postgresql/9.0/main/postgresql.conf
>     /port =        #approximately line 63
>     i
>     port = 5432
>     <Esc>
>     :wq
>     /etc/init.d/postgresql restart 9.0
>     [/code]
> 

Thanks for the feedback! It definitely helps to have people going
through these instructions with a fine-toothed comb!