gnumed-doc 1.1.7-1 / usr / share / doc / gnumed / user-manual / GmManualServerInstall.html

<h1><a name="GNUmed_Server_Installation"></a>  GNUmed Server Installation </h1>
<p />
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 <strong>local</strong> 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.
<p />
Before you attempt to install a GNUmed database, you will need to:
<p />
1) <a href="ConfigurePostgreSQL.html" class="twikiLink">ConfigurePostgreSQL</a>
<p />
2) Download a server package, or a server tarball from the <a href="http://www.gnumed.de/downloads/server/" rel="nofollow" target="_top">official ftp</a> . It's been suggested (Sebastian, July 1 2010) that the files should be in /tmp to help avoid some unhlndled exceptions
<p />
<p />
Now that your system is ready, let's get to the fun stuff. 
<p />
<div class="twikiToc"> <ul>
<li> <a href="#Install_a_new_GNUmed_database"> Install a new GNUmed database?</a> <ul>
<li> <a href="#Be_root_or_postgres"> Be root or postgres</a>
</li> <li> <a href="#About_the_bootstrapper_script"> About the bootstrapper script</a>
</li> <li> <a href="#Erase_any_existing_GNUmed_databa"> Erase any existing GNUmed databases, and their data</a>
</li> <li> <a href="#Debian_Stable_Testing_Unstable_d"> Debian (Stable | Testing | Unstable): deb packages</a>
</li> <li> <a href="#Ubuntu_Hardy_Intrepid_Jaunty_Kar"> Ubuntu (Hardy | Intrepid | Jaunty | Karmic): deb packages</a>
</li> <li> <a href="#Debian_buntu_Mandriva_net_instal"> Debian, (*)buntu, Mandriva: net install</a>
</li> <li> <a href="#Mandriva"> Mandriva</a>
</li> <li> <a href="#open_SuSE_rpm_packages"> openSuSE: rpm packages</a>
</li> <li> <a href="#PCLinuxOS"> PCLinuxOS</a>
</li> <li> <a href="#generic_Linux_and_MacOSX_local_i"> generic Linux and MacOSX: local install</a>
</li> <li> <a href="#Windows"> Windows</a>
</li> <li> <a href="#After_bootstrapping"> After bootstrapping...</a>
</li></ul> 
</li> <li> <a href="#Troubleshooting_and_specific_not"> Troubleshooting and specific notes</a>
</li> <li> <a href="#Inside_the_Bootstrapper"> Inside the Bootstrapper</a>
</li></ul> 
</div>
<p />
<h2 class="twikinetRoundedAttachments"><span class="twikinetHeader"><a name="Install_a_new_GNUmed_database"></a> Install a new GNUmed database? </span></h2>
<p />
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 <strong>any existing GNUmed data</strong> is experimental-only, and can <strong>be permanently destroyed</strong>. If what you wish to do is to <em>upgrade</em> a GNUmed database <em>without</em> losing data, first backup your data using the <a href="GmManualDatabaseBackupRestore.html" class="twikiLink">Data Backup and Restore procedures</a>, and proceed to <a href="GmManualServerUpgrade.html" class="twikiLink">GmManualServerUpgrade</a>.
<p />
<h3><a name="Be_root_or_postgres"></a> Be root or postgres </h3>
<p />
The GNUmed database installation is typically done by user <code>root</code> or by a user who was able to become (using <code>su</code>) <code>postgres</code>. Success of the script under <code>some_other_user</code> is only otherwise possible when <code>some_other_user</code> had been explicitly granted the required access rights. The one exception is the "net install" option, which is run as a regular user&#8230; see below.
<p />
<h3><a name="About_the_bootstrapper_script"></a> About the bootstrapper script </h3>
<p />
Whichever method below is used to obtain the server software, you will need to run the bootstrapper script.
<p />
When it is run, it will <ul>
<li> prompt for a password for the database owner gm-dbo (unless the .conf files already contain a password, even if blank) <ul>
<li> if this password is lost, it can be reset by <ul>
<li> user postgres running the psql command <br>  <code>ALTER ROLE "gm-dbo" ENCRYPTED PASSWORD 'a secret string';</code>
</li> <li> running, as root, the (July 2010) server script: <br> server/gm-set_gm-dbo_password <NEW_PASSWORD>
</li></ul> 
</li></ul> 
</li> <li> the bootstrapper will then <ul>
<li> bootstrap (set up) the baseline <code>v2</code> database
</li> <li> apply successive upgrades to get the database up to the latest version
</li> <li> note: this approach was adopted to ensure a reliable upgrade path to the latest database.
</li></ul> 
</li></ul> 
<p />
Caveats: <ul>
<li> using pre-made packages (from Debian 'testing' or newer) will result in the latest officially-released server, known by its database "version"
</li> <li> servers (databases) that you may bootstrap from CVS, snapshot tarballs, or server "release candidates" are for <strong>testing only</strong> and <strong>must not</strong> 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.
</li></ul> 
<p />
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 <strong>PostgreSQL 8.3</strong> included in Debian 'Lenny' and many other recent Linuxes and likewise available for Mac OS, Windows, Unix. See our <a href="PostgreSQL.html" class="twikiLink">PostgreSQL</a> wiki page for an issue about Postgres 8.4.
<p />
The bootstrapper assumes that, on the target machine on which the bootstrapper would be run: <ul>
<li> <a href="ConfigurePostgreSQL.html" class="twikiLink">ConfigurePostgreSQL</a> has already been done
</li> <li> the <a href="PostgreSQL.html" class="twikiLink">PostgreSQL</a> server itself is running
</li> <li> any existing GNUmed database is non-production (as re-running the script will destroy the data)
</li> <li> any existing GNUmed clients are logged out of any target machine GNUmed
</li></ul> 
<p />
More about the boostrapper is appended (see Inside the Bootstrapper).
<p />
<h3><a name="Erase_any_existing_GNUmed_databa"></a> <em>Erase</em> any existing GNUmed databases, and their data </h3>
<p />
Are you reading this? Truly? The installation process will <strong>erase (destroy) existing GNUmed databases</strong> up to and including the version specified in the bootstrapper.
<p />
<h3><a name="Debian_Stable_Testing_Unstable_d"></a> Debian (Stable | Testing | Unstable): deb packages </h3>
<p />
The default OS in development of GNUmed is Debian <strong>testing</strong>, so <strong>stable</strong> and <strong>unstable</strong> should be supported as long as a sufficiently-current PostgreSQL is installed, configured and working properly. 
<p />
Normally, it would be enough for those evaluating gnumed to do, as <em>root</em> or with <code>sudo</code>, <br>
   <code>apt-get -t testing install gnumed-server</code> <br>
or, if already using a Debian 'testing' distribution, a GUI tool like 'Synaptic package manager'.
<p />
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:
<p /> <ul>
<li> run (as <em>root</em> or with <code>sudo</code>) the system-wide command <code>gm-bootstrap_server</code>
</li> <li> optionally see <ul>
<li> <code>man -k gnumed</code>
</li> <li> <code>man gm-bootstrap_server</code>
</li> <li> <code>man gm-upgrade_server</code>
</li> <li> <code>/usr/share/doc/gnumed-server/README.Debian</code>
</li></ul> 
</li></ul> 
<p />
<h3><a name="Ubuntu_Hardy_Intrepid_Jaunty_Kar"></a> Ubuntu (Hardy | Intrepid | Jaunty | Karmic): deb packages </h3>
<p />
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'.
<p /> <ul>
<li> The line to add manually is referenced in the <a href="https://launchpad.net/~gnumed/+archive/ppa" rel="nofollow" target="_top">GNUmed team's PPA</a>
</li></ul> 
<p />
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:
<p /> <ul>
<li> run (as <em>root</em> or with <code>sudo</code>) the system-wide command <code>gm-bootstrap_server</code>
</li> <li> optionally see <ul>
<li> <code>man -k gnumed</code>
</li> <li> <code>man gm-bootstrap_server</code>
</li> <li> <code>man gm-upgrade_server</code>
</li> <li> <code>/usr/share/doc/gnumed-server/README.Debian</code>
</li></ul> 
</li></ul> 
<p />
<h3><a name="Debian_buntu_Mandriva_net_instal"></a> Debian, (*)buntu, Mandriva: net install </h3>
<p /> <ul>
<li> download the <a href="http://cvs.savannah.gnu.org/viewvc/gnumed/gnumed/server/bootstrap/net_install-gnumed_server.sh?root=gnumed&amp;view=markup" rel="nofollow" target="_top">network-based install script</a> which will download the lastest server release and will take care of installing any packages the server needs, if necessary.
</li> <li> make sure the file is <a href="http://oreilly.com/pub/a/mac/2005/09/09/terminal4.html?page=3" rel="nofollow" target="_top">executable</a>
</li> <li> as <em>a regular user</em>, run <code>./</code> the file <code>net_install-gnumed_server.sh</code> <ul>
<li> at some place(s) in the script, you will need to supply the <em>root</em> password
</li> <li> you may want to inspect the file for bugs, before running it
</li></ul> 
</li></ul> 
<p />
<h3><a name="Mandriva"></a> Mandriva </h3>
<p /> <ul>
<li> there are prepackaged <a href="MandrivaGuideShort.html" class="twikiLink">server RPMs</a> available, thanks go to Michael Schuett and florian/doktor5000
</li> <li> some <a href="MandrivaLinux.html" class="twikiLink">more info</a>
</li></ul> 
<p />
<h3><a name="open_SuSE_rpm_packages"></a> openSuSE: rpm packages </h3>
<p />
Prepackaged RPM packages are available for installation of the GNUmed server. 
<p />
Either use the 1-click installers from <a href="InstallerGuideHomeShort.html#opensuseone" class="twikiAnchorLink">the download page</a>
<p />
<strong>or</strong> use GUI tool like 'Yast package manager' <strong>or</strong>, as <em>root</em> or with <em>sudo</em>, run=zypper install gnumed-server=
<p />
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:
<p /> <ul>
<li> run (as <em>root</em> or with <code>sudo</code>) the system-wide command <code>gm-bootstrap_server</code>
</li> <li> optionally see <ul>
<li> <code>man -k gnumed</code>
</li> <li> <code>man gm-bootstrap_server</code>
</li> <li> <code>man gm-upgrade_server</code>
</li> <li> <code>/usr/share/doc/gnumed-server/README.Debian</code>
</li></ul> 
</li></ul> 
<p />
<h3><a name="PCLinuxOS"></a> PCLinuxOS </h3>
<p /> <ul>
<li> prepackaged <a href="PCLinuxOSGuideShort.html" class="twikiLink">server RPMs</a> are available thanks to Paul Grinberg
</li></ul> 
<p />
<h3><a name="generic_Linux_and_MacOSX_local_i"></a> generic Linux and MacOSX: local install </h3>
<p /> <ul>
<li> setup a directory <ul>
<li> <code>mkdir gnumed-server</code>
</li> <li> <code>cd gnumed-server</code>
</li></ul> 
</li></ul> 
<p /> <ul>
<li> if you want to install an official release <ul>
<li> download the <a href="http://www.gnumed.de/downloads/server/GNUmed-server.latest.tgz" rel="nofollow" target="_top">latest server release</a> <ul>
<li> <code>wget http://www.gnumed.de/downloads/server/GNUmed-server.latest.tgz</code>
</li> <li> <code>tar -xvzf GNUmed-server.latest.tgz</code>
</li></ul> 
</li> <li> you now have a versioned subdirectory, for example <em>GNUmed-v9</em> <ul>
<li> <code>cd GNUmed-v9/server/bootstrap/</code>
</li></ul> 
</li></ul> 
</li></ul> 
<p /> <ul>
<li> if you want the bleeding edge <ul>
<li> checkout the CVS tree
</li> <li> you can use <a href="http://www.gnumed.de/~ncq/gnumed/cvs-access/get-gnumed-anon.sh" rel="nofollow" target="_top">this script</a>
</li></ul> 
</li></ul> 
<p /> <ul>
<li> if your PostgreSQL server is listening on a port other than 5432: <ul>
<li> set the environment variable <code>GM_DB_PORT</code>
</li></ul> 
</li></ul> 
<p /> <ul>
<li> go to <code>server/bootstrap/</code>
</li> <li> run (as <strong>root</strong> or with <em>sudo</em>) <code>bootstrap-latest.sh</code> <ul>
<li> NOTE: Mac OS and Ubuntu do not support the <code>su -c</code> command... without which are disabled one check and one cleanup routine or in other words non-fatal
</li></ul> 
</li></ul> 
<p />
You will need to have taken care of installing any required packages yourself. While you can find the full list of packages <a href="http://cvs.savannah.gnu.org/viewvc/gnumed/gnumed/server/bootstrap/net_install-gnumed_server.sh?root=gnumed&amp;view=markup" rel="nofollow" target="_top">here</a>, Mac users who simply want to get a copy of Postgres and a GNUmed server running locally on their Machine may like to view <a href="http://lists.gnu.org/archive/html/gnumed-devel/2008-01/msg00023.html" rel="nofollow" target="_top">this post</a> to the gnumed-devel list.
<p />
<h3><a name="Windows"></a> Windows </h3>
<p /> <ul>
<li> see <a href="DatabaseOnWindows.html" class="twikiLink">here</a>
</li></ul> 
<p />
<h3><a name="After_bootstrapping"></a> After bootstrapping... </h3>
<p /> <ol>
<li> 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 <a href="ConfigurePostgreSQL.html" class="twikiLink">ConfigurePostgreSQL</a>:
</li>  </ol><ul>
<li> you had hoped to bootstrap as any system user other than <code>root</code> or <code>postgres</code> but cannot
</li> <li> (after bootstrapping) your GNUmed client software cannot connect to a GNUmed server installed on your local machine
</li> <li> clients cannot connect from any machine, other than from your own
</li>  </ul><ol>
<li> Next, restart your <a href="http://www.postgresql.org/" rel="nofollow" target="_top">PostgreSQL</a> server to let any changes take effect. On Linux / Unix including MacOS X the methods are, in decreasing order of advisability:
</li>  </ol><ul>
<li> <code>/etc/init.d/postgresql-8.3 restart</code>
</li> <li> <code>pg_ctlcluster 8.3 main restart</code>
</li> <li> or reboot your machine (think "Windows")
</li></ul> 
<p />
From here, you can proceed to <a href="GmManualStartingGnumed.html#LoggingIn" class="twikiAnchorLink">Starting GNUmed</a> for which you may need to modify the <code>gnumed.conf</code> file of the GNUmed client to enable it to find your newly created backend.The easiest way to do this is - as <strong>root</strong> - copy the file <code>/etc/gnumed/gnumed-client.conf</code> (or, for client versions below 0.4x, the file <code>/etc/gnumed/gnumed.conf</code>) over to <code>/home/userid/.gnumed/</code>. Then log in as that <strong>user</strong> and start GNUmed. 
<p />
By default, the bootstrap inserts a logon banner into one of the tables, warning users that the database to which they are connecting is <strong>not</strong> a production database. This is kept in a single row in the table <code>cfg.db_logon_banner</code> (there can only be one row in that table at any given time). A screenshot can be viewed, attached to <a href="http://lists.gnu.org/archive/html/gnumed-devel/2005-12/msg00263.html" rel="nofollow" target="_top">this archive message</a>. 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.
<p />
Make sure to remove test accounts (<em>any-doc</em>, etc) and to possibly set up your own client config file(s) when you go into production.
<p />
<h2 class="twikinetRoundedAttachments"><span class="twikinetHeader"><a name="Troubleshooting_and_specific_not"></a> Troubleshooting and specific notes </span></h2>
<p /> <ul>
<li> if you see the error message <code>ERROR_STACK_DEPTH exceeded</code> during bootstrapping <ul>
<li> set <code>lc_messages</code> to <code>'C'</code> in <code>postgresql.conf</code>
</li> <li> in recent versions this is done by the bootstrapper automatically
</li></ul> 
</li> <li> more is at <a href="TroubleshootPostgreSQL.html" class="twikiLink">Troubleshoot PostgreSQL</a>
</li></ul> 
<p />
<h2 class="twikinetRoundedAttachments"><span class="twikinetHeader"><a name="Inside_the_Bootstrapper"></a> Inside the Bootstrapper </span></h2>
<p />
This section explains how the bootstrapping works conceptually so that you can derive how to run it on your OS.
<p />
The process roughly goes like this:
<p /> <ul>
<li> create baseline v2 database
</li> <li> import all the necessary tables
</li> <li> import any necessary translation files for the languages you wish to support
</li> <li> grant appropriate access rights
</li> <li> upgrade the v2 baseline database iteratively to produce the latest revision
</li></ul> 
<p />
On GNU/Linux, once Postgres has been installed, and database accounts (e.g. <em>gm-dbo</em>) <a href="ConfigurePostgreSQL.html" class="twikiLink">configured</a>, <em>and</em> the GNUmed program files have been <a href="SourcesFromVcsOnGnuLinux.html" class="twikiLink">installed from CVS</a> or from <a href="InstallerGuideLin.html" class="twikiLink">tarball snapshot</a>, the database installation steps can all be handled automatically by the Python script <em>bootstrap_gm_db_system.py</em> living in <em>gnumed/server/bootstrap/</em>. Several config files for bootstrapping are supplied in that same directory.
<p />
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:
<p />
<pre>
    ./bootstrap&#95;gm&#95;db&#95;system.py --conf-file&#61;&#60;a config file&#62;
</pre>
<p />
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 <code>bootstrap-standard.conf.template</code>.
<p />
<hr />
<p />
<hr />