GNUmed database in a PostgreSQL server on MS Windows

CAUTION do not run the primary bootstrapper script below if you have a working database that needs to be preserved as it will be destroyed (after you had been asked to confirm, of course). Introduced with the server software (beginning with v7 database) are database upgrade scripts selectable from the Windows Start menu. This is cross-referenced in the Administrator Guide.

There are three methods to get a GNUmed database running on MS Windows, elaborated below:
  • use a binary installer – recommended for all levels of user (spares having to set up the required environment variables)
  • manually bootstrap – targeted at software developers
  • restore a database dump using either a GUI tool like 'PgAdmin III' or commandline tool 'pg_restore' or, more simply, following Database Backup & Restore – targeted at system administrators

Install database via graphical user interface (recommended)

First time installation without prior installation of the PostgreSQL database server

  • download the All-in-One server package from the Download page
  • double click the downloaded installer and follow the on-screen installation instructions
    • if in doubt, just click "next" all the time

This will copy all necessary files onto the hard drive, install all dependent software such as PostgreSQL and will prepare the database bootstrapping. Once all files have been copied you are provided with the option to start the GNUmed database bootstrapping process. If that fails, or if you want to delay that step, one can always start that process later by invoking it through the Window start menu entry for GNUmed-server ("...-database").

Installation in the light of a prior installation of the PostgreSQL database server - GNUmed update

  • download the GNUmed-only server package from the Download page
  • double click the downloaded installer and follow the on-screen installation instructions
    • if in doubt, just click "next" all the time

This will copy all necessary files onto the hard drive, install all dependent software such as PostgreSQL and will prepare the database bootstrapping. Once all files have been copied you are provided with the option to start the GNUmed database bootstrapping process. If that fails, or if you want to delay that step, one can always start that process later by invoking it through the Window start menu entry for GNUmed-server ("...-database").

Notes
  • for GNUmed-server.v11.1/WindowsXP: bootstrapping starts automatically, creating the GNUmed-database without any need of input (username or password).
  • for GNUmed-server.v11.1/Windows2000: before installing GNUmed-server it is necessary to install manually PostgreSQL 8.3.7 because this failes in the installation-script of GNUmed-server.v11.1 under Windows2000 (when installing PostgreSQL previously you have to use the same passwords as needed in bootstrapping process after installation of GNUmed-server!)
  • for GNUmed-server until v10.6: a dialog will appear and ask you to provide more information such as the password to access the PostgreSQL database server
  • you can always restart the GNUmed database bootstrap process via the Windows start menu in the GNUmed section

If everything works out a number of GNUmed databases are created inside the PostgreSQL database server. This process is captured in log files. If anything goes wrong, please provide the log files to the GNUmed project team. Those are needed to fix your problem.

Install database manually (advanced, for software developers)

The instructions below depend on PostgreSQL already having been installed on your machine, as explained at GnumedDatabase, as well as ConfigurePostgreSQL already having been done... omission of that step will likely prevent clients from connecting from any other machine as postgresql only accepts local connections by default.

theory of operation

The process roughly goes like this:

  • create databases
  • import all the necessary tables for the services you want to support
  • import any necessary translation files for the languages you wish to support
  • grant appropriate access rights
  • set up service-to-database/server mappings

On MS Windows, once Postgres has been installed and the database account (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 and invisibly 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, where appropriate, by the use of provided batch files. 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>

bootstrap process

First, ensure that you have set up your Windows installation so the installation script will find the neccessary tools. Make sure that the python executable as well as the various postgres tools like 'psql' and 'pg_restore' are in your PATH. You can check by issuing a call like this to the DOS-box.

  echo %PATH%

Now call one of the installation shell scripts provided in 'gnumed/server/bootstrap/':

  bootstrap-latest.bat

bootstrap-latest.bat will install a database that includes everything needed for connecting to it. Don't worry about country-dependent data being installed for countries you don't live in. Using the GNUmed client in your country will work just fine.

Read the output carefully. It will ask you for a password in the beginning, tell you what it is doing and hopefully create the database. While it will create a database owner (gm-dbo) if it did not already exist, the bootstrapper is not designed to insert this gm-dbo into the postgres configuration files, so this step needs to have been done separately as per ConfigurePostgreSQL. A lot of lines will fly by before you should see, at the end of the output and if everything went right, some line like:

Done bootstrapping: We probably succeeded.

In order to connect to this backend from the GNUmed client, you will need to modify its gnumed.conf file as further described at GmManualStartingGnumed#LoggingIn.

Install/Restore database from database backup (for system administrators)

via GNUmed method

refer to wiki topic Database Backup & Restore

via pg_restore

First you need to obtain the database backup. Those are available as mirror backups of our public database from http://publicdb.gnumed.de/~ncq/gnumed/schema either as a schema dump , a data dump or both

If pg_restore is in your PATH issue a command like this:

pg_restore.exe -i -h localhost -p 5432 -U postgres -d gnumed_v2 -s -v "C:\gnumed.backup"

via pgadminIII GUI

(as yet undocumented)


Troubleshooting

1.) if you have manually installed PostgreSQL are not asked for passwords in a black box at the end of the installation of GNUmed package
  • most likely the required PostgreSQL files are not found ( not in your PATH environment variable)
    • Start-->Preferences-->System preferences-->System
    • add path to the files 'python.exe' and 'psql.exe'

2.) If the installation fails with an obscure error message relating to procedural languages not being installed:

  • Make sure the following section in the bootstrapping config files (gnumed/server/bootstrap/*.conf) points to the pgsql libraries on the server.

3.) If you need have installed the All-in-One-Server package passwords are preseeded.

  • Visit the Frequently asked Questions page - FAQ for details.

By default, the bootstrap may insert a banner warning into one of the tables, in order to warn 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.

Make sure to remove test accounts and to possibly set up your own config file if you want to go into production.

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_gm_db_system.conf.sample.
Topic revision: 26 Jun 2011, KarstenHilbert
 
Download.png
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback
Powered by Olark