Skip to content
For the complete DHIS2 documentation index, see llms.txt.
Reference

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

Variable 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.
Variable 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

Variable 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.