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
- if you hoped to bootstrap as any system user other than root or postgres
- if (after bootstrapping) your GNUmed client software cannot connect to a GNUmed server installed on your local machine
- if clients cannot connect from any machine other than your own
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
- setup a directory
-
mkdir gnumed-server
-
cd gnumed-server
- if you want to install an official release
- download the latest server release
-
wget http://www.gnumed.de/downloads/server/GNUmed-server.latest.tgz
-
tar -xvzf GNUmed-server.latest.tgz
- you now have a versioned subdirectory, for example GNUmed-v9
-
cd GNUmed-v9/server/bootstrap/
- if you want the bleeding edge
- if your PostgreSQL server is listening on a port other than 5432:
- set the environment variable
GM_DB_PORT
- go to
server/bootstrap/
- run (as root or with sudo)
bootstrap-latest.sh
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
- download the network-based install script
- make sure the file is executable
- as root run the file (or use sudo)
- yes, system-wide package installation is typically done as root
- you may want to inspect the file for bugs before running it
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
- there are prepackaged server RPMs avaiable, thanks go to Michael Schuett and florian/doktor5000
- some more info
openSuSE
- Prepackaged RPM packages are available for installation of the GNUmed server. Just click the link for a one click installation on openSUSE 10.3, openSUSE 11.0 or manually install like this: zypper install gnumed-client gnumed-server. You might have to add my repository for the packages.
PCLinuxOS
- prepackaged server RPMs are available thanks to Paul Grinberg
Windows
After bootstrapping...
- 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.
- 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.
- Next, restart your PostgreSQL server to let any changes take effect. On Linux / Unix including MacOS X, do (in decreasing order of recommendability):
-
/etc/init.d/postgresql-8.3 restart
-
pg_ctlcluster 8.3 main restart
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
:
-
local samegroup +gm-logins md5
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
-
N
: existing database version you want to upgrade from
-
N+1
: database version you want to upgrade to
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
- download the network-based upgrade script
- make sure the file is executable
- as root run the file (or use sudo)
- yes, system-wide package installation is typically done as root
- you may want to inspect the file for bogosities before running it
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,
- ensure that you have available suitably-configured copies of the client for the new production database
- backup, and then insert a suitable logon banner into, the about-to-be-upgraded database
- stop any and all importers, and point them to the about-to-be new database
- upgrade the old database, resulting in a cloned "new" database
- modify the logon banner of the new database
- restart any and all importers
- depending if it is desired to keep the old database available, reconfigure it to not allow any further connections and/or remove or control the copies of the client that would point to it
Troubleshooting and specific notes
- if you see the error message
ERROR_STACK_DEPTH exceeded
during bootstrapping
- set
lc_messages
to 'C'
in postgresql.conf
- in recent versions this is done by the bootstrapper automatically
- more is at Troubleshoot PostgreSQL
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:
- create baseline v2 database
- import all the necessary tables
- import any necessary translation files for the languages you wish to support
- grant appropriate access rights
- upgrade the v2 baseline database iteratively to produce the latest revision
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
.