GNUmed Server Installation and Upgrade

Remember, the following steps are for the purpose of installing a local database. That is, a database on the computer that you are operating. While a local database is both faster and more usable than the public server, a local server is some work to set up, and the public server does permit basic if slow access to GNUmed for a "first feel".

The bootstrapper requires a minimum Postgres version of 8.1. For maximum satisfaction (especially when searching for patients with diacritics or umlauts in their name), we recommend running on PostgreSQL 8.3.

Be aware that if you skipped the topic ConfigurePostgreSQL in the belief that you could leave Postgres alone, you will run into problems

For further interest in how the bootstrapper works, refer to the bottom section "Inside the Bootstrapper".

On this page:

Installation of a New GNUmed Database.

Apply this method if you do not yet have a GNUmed database on your machine, or if you wish to setup a completely new database. The GNUmed database installation is typically done by user root or by user postgres. Failure of the script to have succeeded (using su) to become user postgres, if the script was run by some other user, can still succeed provided that some other user had been granted proper access rights.

Erasure of existing GNUmed databases, and their data

The installation process will erase existing GNUmed databases up to and including the version specified in the bootstrapper.

GNUmed will bootstrap the baseline v2 database, and will then apply successive upgrades to get the database up to the latest version. This is done to ensure that you will have the latest stable database installed. Using pre-made packages will result in the latest officially-released version.

Performing the installation from the CVS tree will result in the latest in-development version (but beware that sometimes the CVS is buggy and/or not runnable, so do NOT think of it as your main GNUmed database or client).

generic Linux and MacOSX: local install

You will need to have taken care of installing any required packages yourself. While you can find the full list of packages here, Mac users who simply want to get a copy of Postgres and a GNUmed server running locally on their Machine may like to view this post to the gnumed-devel list.

Debian, (*)buntu, Mandriva: net install

The script will take care of installing any packages the server needs if necessary.

The default OS in development of GNUmed is Debian testing, so stable and unstable should be supported as long as PostgreSQL 8.2 or above is installed, configured and working properly.

Mandriva

openSuSE

PCLinuxOS

Windows

After bootstrapping...

  1. While the bootstrapped database will contain the core schema, it will do so without country or language-specific components. Those will have to be added by using one of the /server/bootstrap/bootstrap-XX.conf files where XX represents the ISO country code.

  1. If you you did not yet add into pg_hba.conf the line
   local   samegroup   +gm-logins   md5
at the correct location, enabling GNUmed users to connect to the database, refer to ConfigurePostgreSQL.

  1. Next, restart your PostgreSQL server to let any changes take effect. On Linux / Unix including MacOS X, do (in decreasing order of recommendability):

or reboot your machine (think "Windows")

From here, you can proceed to Starting GNUmed for which you may need to modify the gnumed.conf file of the GNUmed client to enable it to find your newly created backend.The easiest way to do this is - as root - copy the file /etc/gnumed/gnumed.conf (soon to be /etc/gnumed/gnumed-client.conf) to /home/userid/.gnumed/gnumed.conf. Then log in as that user and start GNUmed.

By default, the bootstrap inserts a logon banner into one of the tables, warning users that the database to which they are connecting is not a production database. This is kept in a single row in the table cfg.db_logon_banner (there can only be one row in that table at any given time). A screenshot can be viewed, attached to this archive message. For deactivation, delete the row from the table or, alternatively, replace it with your own logon banner. The latter is especially recommended for anyone who would want to have a remote server, to leave no question as to which database server (clinic, hospital, home, etc.) a client is connecting.

Make sure to remove test accounts (any-doc, etc) and to possibly set up your own client config file(s) when you go into production.


Upgrading a GNUmed database

Apply this method if you have an existing database with patient data which you wish to keep.

GNUmed will upgrade the database stepwise only, say, from v7 to v8. There is no way to skip any steps. During the upgrade an existing database will be cloned and the new database generated from the clone. The original database remains entirely unscathed. Also, during upgrade, GNUmed will attempt to produce a timely backup (which can be a bit costly in time and disk-space) for safekeeping of your precious data. Nevertheless it is a wise idea to keep a second, independently acquired, recent backup around just in case.

To allow upgrades to be taken during bootstrapping, ensure that the following line has already been configured into the appropriate position in pg_hba.conf:

generic Linux, MacOSX and multi-version: local upgrade

Use the upgrade-db.sh script available from the server tarball or CVS tree like this:

upgrade-db.sh N N+1 where

Example upgrading the gnumed_v7 to gnumed_v8:

sh upgrade-db.sh 7 8

The versions must be consecutive. Repeat until the desired version is reached e.g.

...
upgrade-db.sh 5 6
upgrade-db.sh 6 7
upgrade-db.sh 7 8
...

Debian, (*)buntu, SuSE, Mandriva: net upgrade

This script will only upgrade from the previous to the current official release.

Windows

Introduced with the server software (beginning with v7 database) are database upgrade scripts selectable from the Windows Start menu. Naturally, they are just pretty links to the very same procedure described above.

A final, but important, production note

Since old versions of the client will continue to grant access to the old database, you definitely do not want new clinical entries or clinical revisions to be split between two databases and the same goes for any importers at risk of continuing to import data into the old database. Accordingly, in preparation for migrating your production database,

Troubleshooting and specific notes

Inside the Bootstrapper

This section explains how the bootstrapping works conceptually so that you can derive how to run it on your OS.

The process roughly goes like this:

On GNU/Linux, once Postgres has been installed, and database accounts (e.g. gm-dbo) configured, and the GNUmed program files have been installed from CVS or from tarball snapshot, the database installation steps can all be handled automatically by the Python script bootstrap_gm_db_system.py living in gnumed/server/bootstrap/. Several config files for bootstrapping are supplied in that same directory.

The process is further simplified, as described above, by the use of provided shell scripts. These will themselves call the bootstrap script, and will supply the needed command line options by issuing calls like:

    ./bootstrap_gm_db_system.py --conf-file=<a config file>

If you want to tweak things by hand read the config files and the source of the bootstrapping scripts. All the config file parameters are documented in bootstrap-standard.conf.template.