.. SPDX-FileCopyrightText: 2023 Gerald Wiese
..
.. SPDX-License-Identifier: GPL-3.0-or-later

gunicorn
========

| gunicorn is an open source web server that implements the Python Web Server Gateway Interface (WSGI, see PEP 3333).
| There are three connection methods between gunicorn and Nginx:

- If Nginx is on the same system a UNIX socket will be used.
  Therefore a group `wsgi-nginx` is created and both `gnuhealth` & `ẁwww-data` have to be part of that group.
  Otherwise you would either have a world-writable socket or could not access your server.

- Besides HTTP can be used by Nginx if systems are separated but the intranet is considered secure.

- Alternatively it can also provide HTTPS for encrypted communication.

The role ships a config file gunicorn.cfg.py and a systemd service in case of GNU/Linux.

| gunicorn documentation:
| https://docs.gunicorn.org/en/latest/index.html

- **Parameters**:

  - gu_instances: List of gunicorn instances to deploy, selections are provided in defaults
  - gu_upgrade: If true pass `latest` to Ansibles pip module instead of `present`

- **Defaults**:

  - gu_ansible_comment: Put `gu_template_comment` on top of templates if true
  - gu_template_comment: Comment put on top of every template delivered by Ansible
  - gu_https: Spawn HTTPS server if true
  - gu_example_instance: Dictionary containing all parameters that are possibly used by the role, no working default config, just to show what can be configured.
    See `gnuhealth` and `thalamus` roles defaults for example configurations.

- **Variables**:

  - gu_packages: Packages to be installed on the system differentiated by OS family
  - gu_venv_python: Python executable used for virtual environment
  - gu_nginx_group_name: Name of the group to be created for Nginx user & gunicorn user in order to have proper UNIX socket permissions (if necessary)
  - gu_default_mode: Contains default modes for files and directories differentiated by OS