1. Overview

1.1. Introduction

Welcome to the documentation of the Ansible Deployment for GNU Health!

The Ansible playbooks in this project aim to automatically deploy an hospital information system based on GNU Health and other free software. The main elements are:

HIS node: Hospital Information System, core of the GNU Health system (role and playbook just called gnuhealth)

Desktop: Workstation with the GNU Health client to access the HIS node

Orthanc: The DICOM server is not directly part of the GNU Health system but its integration is provided

Thalamus: This is used to build up a GNU Health Federation which contains multiple HIS nodes (still in development)

DHIS2: Health management information system (HMIS), platform for analyzing and reporting, often in a national scale (used for developping the interaction)

Using the playbooks you can easily install the servers - even distributed on multiple systems. Numerous configuration options are realized in order to ease and automize standard configuration steps.

Supported operating systems are the latest Debian, Ubuntu LTS, openSUSE Leap and FreeBSD.

You can find the Ansible repository and the repository of this documentation on Codeberg.

1.2. Use cases

The deployment of GNU Health and other applications is automated in a modular way. Thus the same scripts ca be used for an installation without virtualization, on one Virtual Machine (VM) or distributed on multiple VMs in order to have one distinct system per functionality. The latter case is visualized in the following graphic:

Example of separating every service into a distinct system

All this is realized using the automation and configuration management tool Ansible.

The project was developped with and intended for using VMs. While it is not functional for Docker containers e.g. because it is using systemd for GNU/Linux it does work well with Incus containers.

1.3. Directory structure

For every type of deployment there are .yml files in the playbooks directory. Those are the main scripts that you can execute.

Additionally there are Ansible roles with the corresponding names and other roles getting called implicitly. They are containing the tasks that will install packages and perform configuration steps for creating the desired service.

Your individual configuration is managed in the different inventories folders.

They can be used for having different develop, test & production environments. The default configuration can be found in the dev inventory. It can be used as a base for a test or prod environment.

Inside dev is a subfolder group_vars where you will find directories for different deployments each containing two configuration files vars.yml and vault.yml. The first one contains the main configuration and the second one credentials. Thus it is meant to be encrypted using Ansible Vault (see Securing SSH & passwords).

Some default variables are only stored in roles/<name>/defaults/main.yml. Usually they do not have to be modified but especially if you want to reuse single roles you will need them.

Finally the connection information of the target hosts is given in hosts inside inventories folders.

The test inventory contains an inventory for the test server of this project and shell scripts to generate examples.

If files are needed by different systems those are put into the fetch folder. For some cases - e.g. handling certificates or SSH keys - files have to be transferred from one system to another. Besides the desktop systems having the GNU Health client installed need connection parameters of the server. Those are also written into this folder.

Finally there are tests which are described in detail later on.

You can modify ansible.cfg in the top level directory if you wish to change your Ansible configuration options.

1.4. Installation vs. Administration

This repository contains automated solutions with various configuration options for installation and administration procedures.

Installation refers to calling the playbooks with the _minimal suffix and keeping the default configuration as in the first example.

Administration means extending the functionality by system administration procedures like firewall, backup/restore, etc.

The installation is continuously tested for the latest Debian, Ubuntu LTS, openSUSE Leap and FreeBSD. However the administration features are mainly developed, tested and used for Debian. For productive settings using various roles and configuration options it is currently recommended to use Debian.

1.5. Documentation structure

The Playbooks and Roles chapters describe all the different functionalities in detail.

For a quickstart you can switch directly into the chapter Examples.

Further chapters target questions of Security, System Administration and Project Information in detail.