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?

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

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.