.. SPDX-FileCopyrightText: 2023 Gerald Wiese .. .. SPDX-License-Identifier: GPL-3.0-or-later gnuhealth ========= This role installs the application for the HIS using PyPI. It is not intended to use the builtin `werkzeug` HTTP server but to get executed using uwSGI. Usually this is used as part of the gnuhealth playbook but it could also be integrated in other Ansible setups. Main Installation ----------------- In the beginning some system packages are installed that are needed later on. Then a new operating system user `gnuhealth` without login shell is created. By default the following directories are created: - `/opt/gnuhealth/his` -- home folder - `/opt/gnuhealth/his/etc` -- config folder - `/opt/gnuhealth/his/log` -- log folder - `/opt/gnuhealth/his/data/attach` -- attachments folder - `/opt/gnuhealth/his/local/modules` -- custom modules folder - `/opt/gnuhealth/his/run` -- run folder - `/opt/gnuhealth/his/tls` -- TLS folder - `/opt/gnuhealth/his/venv` -- virtual python environment The run folder contains the UNIX socket if GNU Health & Nginx are on the same system. In case of separate systems a certificate and key will be stored in the TLS folder for enabling HTTPS. The certificate and CRL of PostgreSQL will also be transferred in this directory for verification. The data and local folders only contain one subfolder yet but might get extended. GNU Health itself is installed using the PyPI package `gnuhealth-all-modules` inside the virtual environment. If using openSUSE or FreeBSD Python 3.11 will be installed and used for it in order not to use (soonish) outdated Python versions. After the installation the database created by PostgreSQL before will be initialized using Tryton. Besides the modules specified in `gh_modules` are activated and countries and currencies will get imported. Configuration options for GNU Health itself are prefixed by `gh_`. Templates in use can be found in `roles/gnuhealth/templates`. The application will be executed using uWSGI (see its role). Additional steps ---------------- Optionally you can also add the demo database to your system by setting `gh_demo_db` to true. For using the calendar set `gh_webdav` true as well. If Trytons builtin Cron should be active, you can enable `gh_cron`. The modules are all installed but by default only the core module `health` is activated in the database. You can also extend the list `gh_modules`. Note that you will also get the depending ones activated. If you let the playbooks install Orthanc using a custom CA and want to connect Orthanc to the HIS you can trust this CA by setting `gh_trust_cert_orthanc` to true and specifying the path. In the past GNU Health already shipped some aliases for easing the process of remote support. Those are mainly overtaken and some modified. They are shipped as .gnuhealthrc which is now activated by the .bashrc of the `gnuhealth` user: - `activate`: Activates the virtual python environment (makes former cdexe obsolete) - `cdlogs`: Change to the directory where log files are stored - `cdconf`: Change to the config directory - `cdmods`: Change to the directory containing GNU Health modules - `editconf`: Edit the main config file trytond.conf The traditional gnuhealth-control command is also shipped in a way adapted to the rest of the installation. It can be used for backups on local devices or updates. However it is strongly recommended to use separate systems for automated backups and therefor the barman & restic role can be used. Other installation methods -------------------------- If you want to compare this to other installation strategies have a look at Vanilla Installation https://docs.gnuhealth.org/his/techguide/installation/vanilla.html or openSUSE https://en.opensuse.org/GNUHealth_on_openSUSE Variables --------- - **Parameters**: - gh_version: The version of GNU Health HIS on PyPI as `gnuhealth-all-modules` - gh_psql_uri: The connection string for connecting to the PostgreSQL server - gh_demo_db: Whether a local demo database should be installed - gh_webdav: Whether a service for WebDAV should be created - gh_cron: Whether Tryton Cron should run - gh_tryton_admin_mail: An admin email address visible for Tryton - gh_modules: GNU Health/Tryton modules to activate - gh_trust_cert_orthanc: Whether a certificate of Orthanc should be trusted - gh_trust_certs: Path(s) of the certificate to trust - gh_tryton_pw: Admin password for GNU Health/Tryton client - gh_ssh_key: Whether an SSH key should be created for the `gnuhealth` user - **Defaults**: - gh_home_path: Home directory of `gnuhealth` user - gh_config_path: Directory for config files - gh_log_path: Directory for log files - gh_data_path: Directory for attachments - gh_run_path: Run directory - gh_tls_path: TLS directory - gh_local_modules_path: Path for local customized modules - gh_venv: Where to create the virtual environment - gh_rc_path: Path to put the gnuhealthrc file containing environment variables and aliases, meant to be loaded from .bashrc and for service execution - gh_psql_uri_local: PostgreSQL URI for local connection (UNIX socket) - gh_psql_uri_remote: PostgreSQL URI for remote connection (verify TLS) - gh_prepare_client: Whether a vars file should be prepare for the client installation to overtake connection information - gh_webdav_port: Port of the WebDAV service - gh_install_libreoffice: Install LibreOffice if true - gh_install_libreoffice_recommends: Install recommended packages as well when installing LibreOffice - gh_https: Prepare HTTPS for uWSGI if true - gh_cert: `src` and `dest` for copying certificate - gh_key: `src` and `dest` for copying key - gh_psql_verify_tls: If PostgreSQL TLS should get verified - gh_psql_cert_path: Certificate for verifying PostgreSQL TLS - gh_psql_cert_path_ownca: Default path to pass to `gh_psql_cert_path` when using custom CA - gh_psql_use_crl: Whether GNU Health should hold a Certificate Revocation List (CRL) for PostgreSQL in case of custom CA - gh_psql_crl_path: Path of the CRL - gh_psql_db_name: PostgreSQL database name used for GNU Health - gh_psql_db_user: PostgreSQL user who is owner of the database - gh_psql_domain: Domain name of PostgreSQL server - gh_psql_use_pw: Whether PostgreSQL user has a password - gh_psql_remote: PostgreSQL host is remote and needs to be specified if true - gh_psql_pw: Password of the PostgreSQL user - gh_ssh_dir: Directory for `gnuhealth` users SSH, will be created if not present - gh_ssh_key_path: Path of the private SSH key (public will be the same + '.pub') - gh_ssh_key_remote_user: Remote user that is target of SSH connection for backups - gh_uwsgi_unix_socket: Whether uWSGI should spawn a UNIX socket (otherwise TCP and either uwsgi protocol or HTTPS if `gh_https` is true) - gh_uwsgi_instance: Dictionary containing all the parameters passed to uWSGI role - gh_http_proxy: If true, use HTTP proxy in playbook - gh_http_proxy_address: Address of HTTP proxy to be used - gh_ansible_comment: Put `gh_template_comment` on top of templates if true - gh_template_comment: Comment put on top of every template delivered by Ansible - gh_module_list: List of all available modules that can possibly get added to `gh_modules` - gh_tryton_sao: Install Tryton SAO if true - gh_tryton_sao_path: Path where to install Tryton SAO - **Variables**: - gh_use_testpypi: Whether TestPyPI should be used instead of PyPI, this can be used for testing the `gh_pypi_package` package before publishing - gh_pypi_package: Name of the PyPI package to be installed - gh_demo_db_version: Version of the demo database - gh_demo_db_name: Name of the demo database - gh_packages: Packages to be installed on the system differentiated by OS family - gh_libreoffice_packages: Package names of LibreOffice differentiated by OS family - gh_venv_python: Python executable path to use for venv differentiated by OS family - gh_pipx_path: Pipx executable path differentiated by OS family - gh_bash_path: BASH executable path by OS - gh_tryton_sao_packages: System packages needed for Tryton SAO - gh_default_mode: Contains default modes for files and directories differentiated by OS