.. SPDX-FileCopyrightText: 2023 Gerald Wiese .. .. SPDX-License-Identifier: GPL-3.0-or-later Overview ======== 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 <https://codeberg.org/gnuhealth/ansible>`_ and the repository of this `documentation <https://codeberg.org/gnuhealth/documentation>`_ on `Codeberg <https://docs.codeberg.org/getting-started/what-is-codeberg/>`_. 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: .. figure:: graphics/overview.png 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. 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. 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. 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.