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) Download a server package which can be done

2) Install and ConfigurePostgreSQL and then return to this page.

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

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

Caveats:

The bootstrapper depends on your already having installed a minimum Postgres version of 9.1 (July 2013). We recommend running on the PostgreSQL 9.2 included in Debian 'Jessie' and many other recent Linuxes and likewise available for Mac OS, Windows, Unix.

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

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:

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 server package moves the files necessary for bootstrapping/upgrading databases into /var/lib/gnumed/server/ and also installs a few man pages and commands:

Debian, (*)buntu, Mandriva: net install

Mandriva

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:

PCLinuxOS

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.

Windows

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

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

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.

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.