For the complete DHIS2 documentation index, see llms.txt.

Server Tools Variables¶

Ansible uses variables to handle system differences. In dhis2-server-tools, specific variables are defined PostgreSQL, dhis2 instance, proxy, and monitoring systems. While you can define variables in various places like playbooks, roles, or host files, we mainly define them in the dhis2-server-tools/deploy/inventory/hosts file, created from hosts.template. Customize these variables to fit your environment.

In inventory hosts file, hosts are grouped in [group_names], in our case we have [databases], [instances], [web] and [monitor] groups .Variables not assigned to any specific group belong to the [all] group. To tie variables to a particular group, place them under [group_name:vars], e.g , [instances:vars]. If you want a variable to apply to a specific host, append it to the host line. For example, to add database_host and dhis2_version to the dhis host in the instances group, use the following format:

[instances]
dhis  ansible_host=172.19.2.11  database_host=postgres  dhis2_version=2.39

Another option is to create a file in the inventory/host_vars/ directory with the same name as the host in your inventory/hosts file. The benefit of this approach is that you can encrypt the file using ansible-vault for added security. Any variables you define in the host_vars directory will take precedence over those in inventory/hosts file

touch inventory/host_vars/dhis
vim inventory/host_vars/dhis

Add the variables using yaml syntax as its shown below

ansible_host: 172.19.2.11
database_host: postgres
dhis2_version: 2.39

Here's the list of available configuration parameters and their default values¶

General Variables¶

Variable	Comments
`timezone`	list all available `timezones` with `timedatectl list-timezones` Examples `Europe/Oslo` `Africa/Nairobi`
`ansible_connection`	Depends on the Architecture you are adopting, default is `lxd` Options lxd ← (default), for single server architecture ssh ← Distributed Architecture
`lxd_network`	Here you define a network which your containers will be created into, default is `172.19.2.1/24`
`lxd_bridge_interface`	The name of the created lxd bridge, default is `lxdbr1`

Instance Variables¶

Variable	Comments
`fqdn`	This is the domain used to access dhis2 application Strictly required for Letsencrypt to work. When set, Ansible writes `server.base.url` and `server.https = on` into `dhis.conf`.
`server_base_url`	Optional override for `server.base.url` in `dhis.conf` (CDN or a public hostname that is not inventory `fqdn`). Must be an absolute `https://` URL with no trailing slash. If unset, the value is `https://<fqdn>[/<dhis2_base_path or instance name>]`, with `https_port` appended when it is not 443. The key is omitted when `fqdn` is empty.
`dhis2_base_path`	Public path of the instance. Defaults to the inventory hostname. Use `ROOT` to serve at `/` (no extra path, no trailing slash on `server.base.url`).
`create_db`	Whether the database should be created or not Choices: True ← (default) False
`database_host`	Host to use as your database server Default=`postgres`
`dhis2_war_file`	Source for your dhis2 war file, can either be remote or available locally as file Examples `"https://releases.dhis2.org/2.38/dhis2-stable-2.38.0.war"` `/full/path/for/your/dhis2.war`
`dhis2_version`	You can specify just the major version of dhis2 and it will get its latest stable iteration from https://releases.dhis2.org. If your have both `dhis2_war_file` and `dhis2_version` defined, `dhis2_war_file` wins, Examples `2.39` `2.38`
`heap_memory_size`	This is tomcat Java Heap Memory Size, Example `heap_memory_size=2G`
`dhis2_auto_upgrade`	Enables automatic DHIS2 upgrades when a newer patch version is available. Choices: False ← (default) True Prior to enabling, ensure you have a backup of your instance database.
`app_monitoring`	Enables application monitoring. Currently supports `glowroot`. Options: `glowroot` Example: `app_monitoring=glowroot`

PostgreSQL Variables¶

Proměnná	Comments
`postgresql_version`	PostgreSQL version to install. Default is `16` for fresh installs.
`pg_max_connections`	Maximum allowed database connections.
`pg_shared_buffers`	Shared buffers for PostgreSQL. Recommended: `0.25 x Available_RAM`.
`pg_work_mem`	Work memory per query. Recommended: `(0.25 x Available_RAM) / max_connections`.
`pg_maintenance_work_mem`	Memory for maintenance tasks like index creation. Allocate as much as reasonably possible.
`pg_effective_cache_size`	Approx. `80% of (Available_RAM - maintenance_work_mem - max_connections * work_mem)`.

Proxy Variables¶

Variable	Comments
`email`	Strictly required if you are using Letsencrypt
`proxy`	Proxy software of your choice Options nginx ← (default) apache2
`SSL_TYPE`	This parameter enables to specify whether you'd want to use `letsencrypt` or your own `customssl` certificate, Options letsencrypt ← (default) customssl
`munin_base_path`	Base path for accessing munin, e.g: https://domain.example.com/munin_base_path defaults to `munin`
`munin_users`	A list of users with their corresponding passwords allowed to login to munin: Example: `munin_users: - name: admin password: admin_password - name: user2 password: user2_passsword` Default username and password is admin and district respectively.

Proměnná	Comments
`email`	Strictly required if you are using Let's Encrypt.
`proxy`	Proxy software of your choice. Options: - nginx ← (default) - apache2
`SSL_TYPE`	Choose whether to use `letsencrypt` or a `customssl` certificate. Options: - letsencrypt ← (default) - customssl
`munin_base_path`	Base path for accessing Munin, e.g., `https://domain.example.com/munin_base_path`. Defaults to `munin`.
`munin_users`	A list of users and passwords allowed to log into Munin. See example below.

Example:

munin_users:
  - name: admin
    password: admin_password
  - name: user2
    password: user2_passsword

These variables pertain to the PostgreSQL database host and contain sensitive information. It is advisable to secure them using ansible-vault encryption. You have the flexibility to define these variables in different locations, but it is recommended to place them in the host file within the host_vars directory, as shown below:

dhis2-server-tools/deploy/inventory/host_vars/postgres

Proměnná	Comments
`s3_access_key`	This is a unique identifier for a cloud user or programmatic entity (like an application) that needs to interact with object storage.
`s3_secret_key`	This is a secret piece of information associated with the access key. It is used to digitally sign requests made to object storage and possibly other services. This key must be kept confidential, as it authenticates and authorizes requests on behalf of the access key.
`s3_cluster_id`	Cluster URL for Object Storage is unique to each data center. Different data centers have unique cluster IDs. Refer to Linode Object Storage Guide for Linode.
`s3_bucket`	This is a container or storage resource for storing files in the context of object storage.