# GNUmed Server Installation

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

Before you attempt to install a GNUmed database, you will need to:

1) ConfigurePostgreSQL

2) Download a server package, or a server tarball from the official ftp. It's been suggested (Sebastian, July 1 2010) that the files should be in /tmp to help avoid some unhlndled exceptions

Now that your system is ready, let's get to the fun stuff.

- Install a new GNUmed database?
  - Be root or postgres
  - About the bootstrapper script
  - Erase any existing GNUmed databases, and their data
  - Debian (Stable | Testing | Unstable): deb packages
  - Ubuntu (Hardy | Intrepid | Jaunty | Karmic): deb packages
  - Debian, (*)buntu, Mandriva: net install
  - Mandriva
  - openSuSE: rpm packages
  - PCLinuxOS
  - generic Linux and MacOSX: local install
  - Windows
  - After bootstrapping...
- Troubleshooting and specific notes
- Inside the Bootstrapper
- Removing "test" (demo) data

## Install a new GNUmed database?

Apply the methods on this page if you have never yet installed a GNUmed database on the target machine, or if you are totally certain that any existing GNUmed data is experimental-only, and can be permanently destroyed. If what you wish to do is to upgrade a GNUmed database without losing data, first backup your data using the Data Backup and Restore procedures, and proceed to GmManualServerUpgrade.

### Be root or postgres

The GNUmed database installation is typically done by user `root` or by a user who was able to become (using `su`) `postgres`. Success of the script under `some_other_user` is only otherwise possible when `some_other_user` had been explicitly granted the required access rights. The one exception is the "net install" option, which is run as a regular user… see below.

### About the bootstrapper script

Whichever method below is used to obtain the server software, you will need to run the bootstrapper script.

When it is run, it will

- prompt for a password for the database owner gm-dbo (unless the .conf files already contain a password, even if blank)
  - if this password is lost, it can be reset by
    - user postgres running the psql command
      `ALTER ROLE "gm-dbo" ENCRYPTED PASSWORD 'a secret string';`
    - running, as root, the (July 2010) server script:
      server/gm-set_gm-dbo_password
- the bootstrapper will then
  - bootstrap (set up) the baseline `v2` database
  - apply successive upgrades to get the database up to the latest version
  - note: this approach was adopted to ensure a reliable upgrade path to the latest database.

Caveats:

- using pre-made packages (from Debian 'testing' or newer) will result in the latest officially-released server, known by its database "version"
- servers (databases) that you may bootstrap from CVS, snapshot tarballs, or server "release candidates" are for testing only and must not be used in production as the database schema might stil change. Moreover, while installing from the CVS tree will result in the latest in-development version, beware that sometimes the CVS is buggy and/or not runnable.

The bootstrapper depends on your already having installed 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 the PostgreSQL 8.3 included in Debian 'Lenny' and many other recent Linuxes and likewise available for Mac OS, Windows, Unix. See our PostgreSQL wiki page for an issue about Postgres 8.4.

The bootstrapper assumes that, on the target machine on which the bootstrapper would be run:

- ConfigurePostgreSQL has already been done
- the PostgreSQL server itself is running
- any existing GNUmed database is non-production (as re-running the script will destroy the data)
- any existing GNUmed clients are logged out of any target machine GNUmed

More about the boostrapper is appended (see Inside the Bootstrapper).

### Erase any existing GNUmed databases, and their data

Are you reading this? Truly? The installation process will erase (destroy) existing GNUmed databases up to and including the version specified in the bootstrapper.

### Debian (Stable | Testing | Unstable): deb packages

The default OS in development of GNUmed is Debian testing, so stable and unstable should be supported as long as a sufficiently-current PostgreSQL is installed, configured and working properly.

Normally, it would be enough for those evaluating gnumed to do, as root or with `sudo`,
`apt-get -t testing install gnumed-server`
or, if already using a Debian 'testing' distribution, a GUI tool like 'Synaptic package manager'.

The server package moves the files necessary for bootstrapping/upgrading databases into /var/lib/gnumed/server/ and also installs a few man pages and commands:

- run (as root or with `sudo`) the system-wide command `gm-bootstrap_server`
- optionally see
  - `man -k gnumed`
  - `man gm-bootstrap_server`
  - `man gm-upgrade_server`
  - `/usr/share/doc/gnumed-server/README.Debian`

### Ubuntu (Hardy | Intrepid | Jaunty | Karmic): deb packages

Ubuntu packages for the GNUmed server part are available through the GNUmed team's personal package. To get the 'gnumed-server' package one needs to add the software repository 'GNUmed PPA' to the list of sources. This can be achieved through tools like 'Synaptic package manager'.

- The line to add manually is referenced in the GNUmed team's PPA

The server package moves the files necessary for bootstrapping/upgrading databases into /var/lib/gnumed/server/ and also installs a few man pages and commands:

- run (as root or with `sudo`) the system-wide command `gm-bootstrap_server`
- optionally see
  - `man -k gnumed`
  - `man gm-bootstrap_server`
  - `man gm-upgrade_server`
  - `/usr/share/doc/gnumed-server/README.Debian`

### Debian, (*)buntu, Mandriva: net install

- download the network-based install script which will download the lastest server release and will take care of installing any packages the server needs, if necessary.
- make sure the file is executable
- as a regular user, run `./` the file `net_install-gnumed_server.sh`
  - at some place(s) in the script, you will need to supply the root password
  - you may want to inspect the file for bugs, before running it

### Mandriva

- there are prepackaged server RPMs available, thanks go to Michael Schuett and florian/doktor5000
- some more info

### openSuSE: rpm packages

Prepackaged RPM packages are available for installation of the GNUmed server.

Either use the 1-click installers from the download page

or use GUI tool like 'Yast package manager' or, as root or with sudo, run=zypper install gnumed-server=

The server package moves the files necessary for bootstrapping/upgrading databases into /usr/lib/gnumed/server/ and also installs a few man pages and commands:

- run (as root or with `sudo`) the system-wide command `gm-bootstrap_server`
- optionally see
  - `man -k gnumed`
  - `man gm-bootstrap_server`
  - `man gm-upgrade_server`
  - `/usr/share/doc/gnumed-server/README.Debian`

### PCLinuxOS

- prepackaged server RPMs are available thanks to Paul Grinberg

### 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`
  - NOTE: Mac OS and Ubuntu do not support the `su -c` command... without which are disabled one check and one cleanup routine or in other words non-fatal

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.

### Windows

- see here

### After bootstrapping...

1. Were there problems during attempted bootstrap, or with users trying to connect to the database? Here are signs that you must recheck proper postgres configuration as per ConfigurePostgreSQL:

- you had hoped to bootstrap as any system user other than `root` or `postgres` but cannot
- (after bootstrapping) your GNUmed client software cannot connect to a GNUmed server installed on your local machine
- clients cannot connect from any machine, other than from your own

1. Next, restart your PostgreSQL server to let any changes take effect. On Linux / Unix including MacOS X the methods are, in decreasing order of advisability:

- `/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-client.conf` (or, for client versions below 0.4x, the file `/etc/gnumed/gnumed.conf`) over to `/home/userid/.gnumed/`. 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.

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

## Removing "test" (demo) data

This can be achieved by two methods.

If you already created real patients, and must keep the clinical data that you entered for them, you can selectively remove the records pertaining to each of the demo patients, one at a time. You should of course first back up. Then, you can run the script `gm-remove_person.sh` located in the server package, supplying the following parameters: (1) the target version of the database (`gnumed_vXX` where XX designates a version such as 18) and (2) the primary key unique number for the patient who is to be removed (NNN):

        ./gm-remove_person.sh gnumed_vXX NNN

You will be prompted for the master password for the database user-owner, gm-dbo.

If you did not yet create any clinical data which needs keeping, you can re-bootstrap after first disabling the import of the test data. Until we have had a chance to include those steps on the wiki, we can refer you to this thread on the list archive.