GNU Health/Installation

From Wikibooks, open books for an open world
Jump to: navigation, search


The latest stable GNU Health has the following requirements:

  1. Operating System: GNU Health is Operating System independent, although we highly recommend the use of a Free OS (such as GNU/Linux or FreeBSD)
  2. Database: PostgreSQL
  3. Python: >= 2.7 < 3.0
  4. Tryton: = 3.8
  5. BASH Shell
  6. PIP version for Python 2, verify through:
    pip --version

    You should see the python2.7 part, as in:
    pip x.x.x from /usr/local/lib/python2.7/site-packages (python 2.7)
    If you see python3.x then stop and get the pip for python 2.

Installing GNU Health on GNU/Linux and FreeBSD[edit]

Operating System requirements[edit]

The following table contains the instructions to setup your operating system for a standard GNU Health installation. The operating systems and their version shown in the list have been tested using the instructions for each OS.

The installation instructions for the different Operating Systems and distributions have been done on fresh installation. When possible and for simplicity sake, only the server environment was installed, without desktop. No firewall was configured (we will cover this on the security section), and the SSH server was installed.

The instructions - written here - have been applied and verified with the following OS as shown below.

Operating System Version Link Notes
Arch Linux 2015.06.01 Arch Linux setup
Debian 7.8 Debian setup
CentOS 7.1 CentOS setup
FreeBSD 10.01 FreeBSD setup
OpenSUSE Leap / Tumbleweed OpenSUSE setup
Red Hat 7.1 Red Hat setup
Ubuntu 14.04 Ubuntu setup
Trisquel 7.0 Trisquel setup

Setting up Network Time Protocol (NTP)[edit]

In order to properly run GNU Health, you need to make sure that the time in both the server (database and central instance) and the clients are properly set and in sync . The best way to do this is to keep your clock synchronized with a NTP Server .

This is a critical step, not only for the smooth functioning of GNU Health, but also because many documents will have a timestamp associated that can have legal value.

Creating the Operating System User[edit]

The following steps will create the GNU Health operating system user. Please note that many operating systems give you the option to create a regular user at installation time. If you already created the "gnuhealth" operating system user, you can skip this section, otherwise, create it now.

Run the following command as root:

adduser gnuhealth

Note: If your Operating System does NOT include the adduser command, you can use the useradd command

useradd -m gnuhealth

Verify PostgreSQL authentication method[edit]

Note : You can skip this section if you made a standard installation on FreeBSD or Arch Linux

PostgreSQL uses different authentication methods (MD5, ident, trust ... ). Depending the Operating System, the postgreSQL server authentication method will vary.
The standard GNU Health installation uses the trust authentication method, so you need to check the postgreSQL authentication file configuration.

Locate the pg_hba.conf file and verify that the trust method is set. The location of this configuration file varies across operating systems; under UNIX/Linux, the full pathname of the file can be obtained with the following command, to be executed as root:

su - postgres -c "psql -t -P format=unaligned -c 'show hba_file'"

You may need to start the postgres server at least one time as this file may be created during first startup. Usually this file is located at /etc/postgresql/9.x/main or /var/lib/pgsql/data

An example configuration file entry specifying use of the trust method is given in the following line:

local   all             all                                     trust

The following example in particular may address issues with establishing a working database connection as reported in the context of the creation of the GNU Health database upon first use of the Tryton client (see further down; Symptom: the "Create" button is not displayed):

host    all             all               trust

Make sure you edit the file as user 'postgres', otherwise - as root - postgres may have trouble reading the changed file. After any changes to the file, the postgreSQL server needs to be restarted.

Many authentication errors (e.g., database connection errors) arise because of not having correctly configured this file. Of course, you can use other authentication methods, and you can adapt the tryton / GNU Health configuration file to each of them. For the sake of simplicity, we based the documentation and sample files on this book on one (trust) specific method.

Make sure you restart your postgresql server: sudo service postgresql restart

Creating the Database User[edit]

The following command switches to the postgres administration user and gives permissions to your newly created gnuhealth administrator:

Execute, as root:

su - postgres -c "createuser --createdb --no-createrole --no-superuser gnuhealth"

Downloading and Installing GNU Health[edit]

Running the GNU Health Installer[edit]

Become user gnuhealth:

su - gnuhealth 
cd $HOME

Download GNU Health from[edit]

Symbol version newer.svg

This section applies to version 3.0 of GNU Health.

For version >= 3.0, download the following to get the latest gnuhealth_setup installation program


Verify the package signature[edit]

First get the signing key if you haven't done so:

gpg --recv-key 0xEADA01E3E44B8011

The key is issued by Luis Falcon (meanmicio at GNU) <> and its fingerprint is 14C7 FD13 6274 9706 D602 FBE2 EADA 01E3 E44B 8011. This information can be seen issuing:

gpg --with-fingerprint --list-keys 0xEADA01E3E44B8011

Then, verify the signature, using the matching version number for the latest. For instance, if latest GNU Health version is 3.0.5, then

Download the detached signature:


Verify the package using the detached signature :

gpg --verify gnuhealth-3.0.5.tar.gz.sig gnuhealth-latest.tar.gz

If the file is correctly validated, the output should be something like:

   gpg: Signature made Sun Jan 31 09:00:14 2016 ART
   gpg:                using DSA key 0xEADA01E3E44B8011
   gpg: Good signature from "Luis Falcon (meanmicio at GNU) <>" [unknown]
   gpg: WARNING: This key is not certified with a trusted signature!
   gpg:          There is no indication that the signature belongs to the owner.
   Primary key fingerprint: 14C7 FD13 6274 9706 D602  FBE2 EADA 01E3 E44B 8011

The important part is the Good signature from "Luis Falcon ....". The WARNING means that, even if the file and signature are OK and validated correctly, you aren't trusting that key; and it's OK. You can read more about this in The GNU Privacy Handbook, Chapter 3. Key Management.

Uncompress the file:

tar xzf gnuhealth-latest.tar.gz

Change to the GNU Health installation directory matching your version :

cd gnuhealth-3.0.3

Run the gnuhealth_setup installation program

./gnuhealth-setup install

Finally, enable the BASH environment for the gnuhealth user.

source "$HOME"/.gnuhealthrc

Activate Network Devices for the JSON-RPC Protocol[edit]

The Tryton GNU Health server listens to localhost at port 8000, not allowing direct connections from other workstations.


You can edit the parameter listen in the [jsonrpc] section , to activate the network device so workstations in your net can connect. For example, the following block

listen = *:8000

will allow to connect to the server in the different devices of your system.

Setting up a Local Directory for Attachments[edit]

By default, Tryton uses a system-wide directory to store the attachments. In GNU Health is advisable to keep the attachments in the gnuhealth user space.

Edit the server configuration file trytond.conf and enter the attach directory under the [database] section, for instance:

path = /home/gnuhealth/attach

Configuring the Log File (optional)[edit]

Since GNU Health 2.8, the way the server logs and tracks events is based on a log configuration file, that resides in the config directory "${GNUHEALTH_DIR}"/tryton/server/config/.

A default version is shipped, called gnuhealth_log.conf.
It looks something like this:

keys: simple

keys: rotate, console

keys: root

format: [%(asctime)s] %(levelname)s:%(name)s:%(message)s
datefmt: %a %b %d %H:%M:%S %Y

class: handlers.TimedRotatingFileHandler
args: ('/home/gnuhealth/gnuhealth/logs/gnuhealth.log', 'D', 1, 30)
formatter: simple

class: StreamHandler
formatter: simple
args: (sys.stdout,)

level: WARNING
handlers: rotate, console

In this example (and in the standard file) the log file is written in the default logs directory. You can change it to fit your specific installation.

In order to use logging, you need to provide the --logconf option, along with the path to the log configuration file gnuhealth_log.conf as argument, when invoking the Tryton server, in the next section (e.g., trytond --logconf "${GNUHEALTH_DIR}"/tryton/server/config/gnuhealth_log.conf ...).

For more information, check the following resources:

Booting up the Tryton Server[edit]

Change to your newly installed system (use the alias cdexe )


and boot the server.

./trytond --verbose
Helpful Hint!
use the --logconf option to write the log file

You should see something like this. Pay attention at the last line INFO:server:starting JSON-RPC protocol on *:8000

Note : the "--verbose" argument is optional. It is used in this case so you can see the main configuration parameters.

[Wed Jan 14 11:01:20 2015] INFO:server:using /home/gnuhealth/gnuhealth/tryton/server/config/log.conf as logging configuration file
[Wed Jan 14 11:01:20 2015] INFO:trytond.server:using /home/gnuhealth/gnuhealth/tryton/server/config/trytond.conf as configuration file
[Wed Jan 14 11:01:20 2015] INFO:trytond.server:initialising distributed objects services
[Wed Jan 14 11:01:20 2015] INFO:trytond.server:starting JSON-RPC protocol on *:8000

Installation of the Tryton Client[edit]

Standard Method[edit]

FreeBSD, GNU/Linux and other *NIX[edit]

Download and extract the Tryton client from the tryton site [1]

Install python dependencies :

pip2 install --user python-dateutil

Untar the client tarball:

tar -xzvf tryton-3.8.3.tar.gz

Excute the client:

cd tryton-3.8.3/bin 

Microsoft Windows[edit]

Download the Tryton client [2].

Follow the instructions.

Alternative Method (PIP)[edit]

Note: There are some issues with the local installation of the Tryton client and PIP. We recommend using the standard method. Following are the instructions on how to install the client system-wide (without the --user option).

pip install "tryton>=3.8,<3.9"

If you have an older Tryton client (installed with PIP), you can upgrade it to the latest version with the following command:'

pip install --upgrade tryton

The following command will boot your tryton client


Alternative Method (System Packages)[edit]

Instead from source as described above, you can install the Tryton Client from pre-build packages as well. Debian and openSUSE offer packages that you can install with your systems package manager.

Setting the Tryton Client Tabs Position for GNU Health[edit]

Setting the tabs position

Before you start the installation of the database, you need to set the tabs position to be on "Top". This will produce the optimal navigation.

The following action in the Tryton client will set it: Options → Form → Tabs Position → Top.

Finally, save your client preferences Options → Save Options.

Creating the GNU Health database[edit]

Login Screen

The first step is to create a database that will hold all the information for your GNU Health system.

All GNU Health information is stored in a PostgreSQL database, and processed by the Tryton kernel. No action is needed at the operating system level to create or manage the database, as all can be done via the Tryton / GNU Health frontend.

To create a database, open your Tryton client. You will be presented with the following login popup window:

Click on Manage profiles, then click on Add. Give your new connection a name on the left side, and fill the fields on the right side. If you're doing the installation on the same machine, choose localhost as the hostname. Example:

Connection Profile

Click on the Create button, the following popup appears:

Create Database

The default Tryton server password is admin (you can change it later). Give your database a name, and enter a new admin password twice. Note: this will be the password of the super-user for your new database, so use a strong password when dealing with production servers.

Check in the server log (or console) if any error occurs. If so, try to fix the problem (ie. any Python module missing or some unmet dependencies), drop the database just created and repeat the procedure.

After the database is created, click OK. You're now ready to log in!

Logging into the Application[edit]

Now that you're back at the login screen, you'll notice that the selected profile is the one you've just created. Fill in the login form:

  • User name: the one you used previously usually, admin
  • Password: the one entered twice in the previous section

Installing the Default Modules[edit]

From this point on, you will use the client for almost every process. Start with the installation of the basic functionality:

  1. After you've created the database, the system will ask you to create some new users. You can skip this step for now.
  2. You are then presented with a list of modules that will provide the functionality you desire. If you don't see the Modules window, navigate to it on the left side: Administration → Modules → Modules.
  3. Select the health_profile module, and click on Mark for installation:
    GNU Health Module selection.png
  4. Click on the Action icon (a blue rotated square) and select Perform Pending Installation/Upgrade:
    GNU Health Module selection - Marked for installation.png
  5. Tryton will automatically select all the dependent modules required for the installation:
    GNU Health Perform Pending Installation-Upgrade.png
  6. Click on Start Upgrade. This process will take a while, depending on the computer where GNU Health is being installed on. Once it's done, the following message appears:
    GNU Health system upgrade done message.png

Creating a Company[edit]

The next thing you need to do is to create the initial company, that will be your health center. You will be presented with a wizard to create it.

Create Initial company

Press F3 to create the new company.

Note: At the party form, please make sure you set the institution attribute . You will link this company to your main health institution later on. Please refer to the screenshot provided in this section for details.

Initial configuration. Creating the main company associated to the party (health institution)

Disabling demo users in Production environments[edit]

GNU Health comes with a set of pre-defined users for demo purposes. They all have the suffix "demo_" ( demo_doctor, demo_front_desk, demo_nurse... ).

Please deactivate them in production environments.

To deactivate the users, follow the following path : Administration -> Users -> Users

Deactivation of demo users in production environments

In filters, you can choose : login name : demo_

Unset the "active" flag of each of them. The demo users are now de-activated in your environment.

Look at the provided screenshot for further details.

Congratulations! You have completed the initial installation of GNU Health. In the next chapter we will discuss how to add functionality by installing additional modules.

Epidemiology · Administration