# 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.
  - Erasure of existing GNUmed databases, and their data
  - generic Linux and MacOSX: local install
  - Debian, (*)buntu, Mandriva: net install
  - Mandriva
  - openSuSE
  - PCLinuxOS
  - Windows
  - After bootstrapping...
- Upgrading a GNUmed database
  - generic Linux, MacOSX and multi-version: local upgrade
  - Debian, (*)buntu, SuSE, Mandriva: net upgrade
  - Windows
  - A final, but important, production note
- Troubleshooting and specific notes
- Inside the Bootstrapper

## 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
  - checkout the CVS tree
  - you can use this script

- 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

- see here

### 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):

- `/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`.