{"id":19005058,"url":"https://github.com/dhis2/dhis2-server-tools","last_synced_at":"2026-03-05T07:06:18.576Z","repository":{"id":40315826,"uuid":"475369422","full_name":"dhis2/dhis2-server-tools","owner":"dhis2","description":"Tools to support installation and management of DHIS2","archived":false,"fork":false,"pushed_at":"2025-03-17T03:02:20.000Z","size":2177,"stargazers_count":21,"open_issues_count":4,"forks_count":21,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-04-17T10:24:55.520Z","etag":null,"topics":["ansible"],"latest_commit_sha":null,"homepage":"","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dhis2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-03-29T09:23:17.000Z","updated_at":"2025-03-29T07:33:32.000Z","dependencies_parsed_at":"2023-02-17T18:31:09.126Z","dependency_job_id":"d56d3f55-b101-4429-b600-b877bd5e9d42","html_url":"https://github.com/dhis2/dhis2-server-tools","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fdhis2-server-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fdhis2-server-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fdhis2-server-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhis2%2Fdhis2-server-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhis2","download_url":"https://codeload.github.com/dhis2/dhis2-server-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250303662,"owners_count":21408644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansible"],"created_at":"2024-11-08T18:25:55.738Z","updated_at":"2026-02-10T10:09:50.698Z","avatar_url":"https://github.com/dhis2.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"Table of contents\n---\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [Introduction](#introduction)\n* [Installation with LXD containers](#installation-with-lxd-containers)\n\t* [Step 0 — Before you start](#step-0--before-you-start)\n\t* [Step 1 — SSH to your server (where you want to install DHIS2) and enable firewall.](#step-1--ssh-to-your-server-where-you-want-to-install-dhis2-and-enable-firewall)\n\t* [Step 2 — Grab the deployment tools from github](#step-2--grab-the-deployment-tools-from-github)\n\t* [Step 3 —  Create inventory hosts file](#step-3---create-inventory-hosts-file)\n\t* [Step 4 — Set fqdn, email, and timezone](#step-4--set-fqdn-email-and-timezone)\n\t* [Step 5 — The Install](#step-5--the-install)\n* [Install on physical/virtual servers.](#install-on-physicalvirtual-servers)\n\t* [Step 1: Before you start, make sure you have the following:](#step-1-before-you-start-make-sure-you-have-the-following)\n\t* [Step 2: Access deployment server (ansible-controller) via SSH](#step-2-access-deployment-server-ansible-controller-via-ssh)\n\t* [Step 3: Install ansible on the deployment server](#step-3-install-ansible-on-the-deployment-server)\n\t* [Step 4: Grab deployment tools from github](#step-4-grab-deployment-tools-from-github)\n\t* [Step 5: Create hosts file (from the hosts template)](#step-5-create-hosts-file-from-the-hosts-template)\n\t* [Step 6: Set fqdn, email, timezone and `ansible_connection=ssh`](#step-6-set-fqdn-email-timezone-and-ansible_connectionssh)\n\t* [Step 7:  Ensure connection to the managed hosts works](#step-7--ensure-connection-to-the-managed-hosts-works)\n\t* [Step 8: Run the playbook](#step-8-run-the-playbook)\n* [Adding a new instance](#adding-a-new-instance)\n* [Using a Custom TLS Certificate](#using-a-custom-tls-certificate)\n* [Conclusion](#conclusion)\n* [Other important links](#other-important-links)\n\n\u003c!-- vim-markdown-toc --\u003e\n---\n\n## Introduction \nThis is a quick DHIS2 install guide using [ansible](https://www.ansible.com/). At the end, you will have\none or more dhis2 instances running, configured with postgreSQL database and\nnginx or apache2 proxy. Out of the box, you'll benefit from comprehensive application and server resource monitoring with Glowroot APM (Application Performance Monitoring) and a Munin instance. \n\nAt the moment, the tools support two deployment architectures:\n- [Installation with LXD containers](#installation-with-lxd-containers) (single server)\n- [Installation on physical/virtual servers](#install-on-physicalvirtual-servers) (multiple servers)\n\nYou can also do a hybrid of both. [Read more on Architectures](./docs/Deployment-Architectures.md)\n\n## Installation with LXD containers\n### Step 0 — Before you start\nEnsure you have:\n- Linux server, minimum 4GB RAM, 2 CPU cores\n  - Ubuntu 22.04 or\n  - Ubuntu 24.04 \n- SSH Access to the server\n- A non-root user with sudo privileges.\n\n### Step 1 — SSH to your server (where you want to install DHIS2) and enable firewall. \n- SSH to your server, Secure/harden SSH, allow SSH port on the firewall and\n  finally enable the firewall. Be careful not to lock yourself out. Remember to\n  allow your preferred ssh port before enabling the firewall. \n  ```\n  sudo ufw limit 22 # Assuming you did not change default ssh port (22)\n  sudo ufw enable\n  ```\n\n### Step 2 — Grab the deployment tools from github\n- Access the server and clone the deployment tools in your preferred directory by invoking below command\n  ```\n  git clone https://github.com/dhis2/dhis2-server-tools.git\n  ```\n\n### Step 3 —  Create inventory hosts file\n- Create the `hosts` file using the already existing template,\n  `hosts.template`. \u003cbr\u003e\n  Use the command below if you are in the directory you cloned the tools in.\n  ```\n  cp dhis2-server-tools/deploy/inventory/{hosts.template,hosts}\n  ```\n\n### Step 4 — Set fqdn, email, and timezone\n- Edit `dhis2-server-tools/deploy/inventory/hosts` file and set `fqdn`, and `email`\n  if you have any (you can leave them empty if you do not have).\n- Set your preferred `timezone`, you can leave other settings to their set defaults. \n  ```\n  vim dhis2-server-tools/deploy/inventory/hosts\n  ```\n  Below is an example screenshot\n```ini\n# variables applying to all hosts,\n[all:vars]\n# if you do not set fqdn, you dhis2 will be set up with self-signed certificate\nfqdn=your-domain.example.com\n# required for LetsEncrypt certificate notification.\nemail=your-email@example.com\n# timedatectl list-timezones to list timezones\n# Example: timezone=Africa/Nairobi\ntimezone=your-timezone\n# Options: lxd, ssh defaults to lxd.\nansible_connection=lxd\n```\n\n  _**NOTE**: When the installation is on a single host with LXD, ensure your lxd_network is unique and not overlapping with any of your host network._ \n\n###  Step 5 — The Install\n- Run `deploy.sh` script from within `dhis2-server-tools/deploy/` directory. \n  ```\n  cd dhis2-server-tools/deploy/\n  sudo ./deploy.sh\n  ```\n- After the script finishes running (without errors), access your DHIS2, Glowroot and Munin monitoring instances:\n  \u003e **Note:** `\u003chostname\u003e` = your `fqdn` if defined, otherwise your server's IP address.\n  ```\n  https://\u003chostname\u003e/dhis\n  https://\u003chostname\u003e/dhis-glowroot\n  https://\u003chostname\u003e/munin\n  ```\n\n## Install on physical/virtual servers.\n### Step 1: Before you start, make sure you have the following:\n- A deployment server - This server is going to be your ansible-controller.\u003cbr\u003eDHIS2\n  setup on the backend application server will be done from here. We will be using\n  deployment server and ansible-controller interchangeably in this guide. \n  - It should run either Ubuntu 22.04 or 24.04 \n  - It should have working and tested SSH access to the managed hosts (backend\n    application servers). SSH key-based authentication is advisable\u003cbr\u003e \n    Deployment will be working with SSH connection. \n\n    ```mermaid\n    graph LR\n        A[Deployment Server\u003cbr/\u003eAnsible Controller] --\u003e|ssh| B[Database Server\u003cbr/\u003ePostgreSQL]\n        A --\u003e|ssh| C[DHIS2\u003cbr/\u003eApplication Server]\n        A --\u003e|ssh| D[Proxy\u003cbr/\u003eNginx/Apache2]\n        A --\u003e|ssh| E[Monitoring Server\u003cbr/\u003eMunin]\n        F[\"./inventory/\u003cbr/\u003e- hosts\u003cbr/\u003e- group_vars\u003cbr/\u003e- host_vars\"] -.-\u003e A\n        subgraph Managed Hosts\n            B\n            C\n            D\n            E\n        end\n    ```\n- Backend Servers (managed hosts) - These are the servers that will be running\n  your DHIS2 components, i.e database(PostgreSQL, DHIS2, Monitoring, Proxy)\n  - They all should be running Ubuntu 22.04 or 24.04 \n  - Be accessible (via ssh) from the deployment server.\n\n### Step 2: Access deployment server (ansible-controller) via SSH \n- SSH to the ansible-controller, Secure/Harden ssh, allow SSH port on the firewall,\n  and finally enable the firewall. Be careful not to lock yourself out.\n  Remember to allow your preferred SSH port before enabling the firewall.\n\n  ```\n  sudo ufw limit 22 # Assuming you did not change default SSH port (22)\n  sudo ufw enable\n  ```\n\n### Step 3: Install ansible on the deployment server\n  ```\n  sudo apt -y update\n  sudo apt install -y software-properties-common\n  sudo apt-add-repository --yes --update ppa:ansible/ansible\n  sudo apt install -y ansible\n  ```\n\n### Step 4: Grab deployment tools from github\n-  Access the server and clone the deployment tools in your preferred directory by invoking below command \n  ```\n  git clone https://github.com/dhis2/dhis2-server-tools\n  ```\n\n### Step 5: Create hosts file (from the hosts template) \n- Create the hosts file using the already existing template, hosts.template.\n  Use the command below if you are in the directory you cloned the tools in.\n  ```\n  cp dhis2-server-tools/deploy/inventory/{hosts.template,hosts}\n  ```\n\n### Step 6: Set fqdn, email, timezone and `ansible_connection=ssh`\n- Edit the inventory hosts file and configure the following variables:\n  - `fqdn` — your domain name. Leave empty if you don't have one (DHIS2 will use a self-signed certificate)\n  - `email` — for LetsEncrypt certificate notifications\n  - `timezone` — use `timedatectl list-timezones` to list available options\n  - `ansible_connection=ssh` — **required** for physical/virtual server deployments\n  ```\n  vim dhis2-server-tools/deploy/inventory/hosts\n  ```\n  ```ini\n  # variables applying to all hosts,\n  [all:vars]\n  # if you do not set fqdn, you dhis2 will be set up with self-signed certificate\n  fqdn=your-domain.example.com\n  # required for LetsEncrypt certificate notification.\n  email=your-email@example.com\n  # timedatectl list-timezones to list timezones\n  # Example: timezone=Africa/Nairobi\n  timezone=your-timezone\n  # Options: lxd, ssh defaults to lxd.\n  ansible_connection=ssh\n  ```\n\n### Step 7:  Ensure connection to the managed hosts works\n- [Read More on how you can configure SSH](./docs/SSH-Connection.md)\n- You will need to setup SSH connection from your deployment server to your backend application servers. \n- Both password or key-based authentication would work. Key-based authentication\n  is encouraged if you want your deployment to run fully automated (no prompts\n  for SSH passwords). Use ansible ping module to test your connection to all the\n  backend hosts except localhost (127.0.0.1)\n\n  ```\n  cd dhis2-server-tools/deploy/\n  ansible 'all:!127.0.0.1' -m ping \n  ```\n  If your SSH connection is successful, you will see SUCCESS messages like below:\n  ```json\n  dhis | SUCCESS =\u003e {\n      \"ansible_facts\": {\n          \"discovered_interpreter_python\": \"/usr/bin/python3\"\n      },\n      \"changed\": false,\n      \"ping\": \"pong\"\n  }\n  monitor | SUCCESS =\u003e {\n      \"ansible_facts\": {\n          \"discovered_interpreter_python\": \"/usr/bin/python3\"\n      },\n      \"changed\": false,\n      \"ping\": \"pong\"\n  }\n  ```\n  \n### Step 8: Run the playbook\n- Since installing packages on the remote server needs sudo, you will be using `-K` or `--ask-become-pass` \n  ```\n  cd dhis2-server-tools/deploy/\n  ansible-playbook dhis2.yml -u=username  --ask-become-pass --ask-pass\n  ```\n\u003ctable\u003e\n\u003ctr\u003e\n    \u003cth style=\"text-align: left; vertical-align: top;\"\u003eDescription\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctd\u003e\n  \u003ccode\u003e-k or --ask-pass \u003c/code\u003e\u003cspan\u003e\u0026#8212;\u003c/span\u003e prompts for SSH password \u003cbr\u003e\n  \u003ccode\u003e-K or --ask-become-pass\u003c/code\u003e\u003cspan\u003e\u0026#8212;\u003c/span\u003e enables sudo password prompt, you can set \u003ccode\u003eansible_sudo_pass=STRONG_PASSWORD\u003c/code\u003e to avoid prompts \u003cbr\u003e\n  \u003ccode\u003e-u\u003c/code\u003e\u003cspan\u003e\u0026#8212;\u003c/span\u003e username for SSH connection \u003c/td\u003e \u003c/tr\u003e\n\u003c/table\u003e\n\nNOTE:\n- When your SSH connection is based on keys, there's no need for the `-k` flag\n- If you don't specify an SSH username, it will automatically use currently logged in username.\n\n- After the playbook finishes running (without errors), access your DHIS2, Glowroot and Munin monitoring instances:\n  \u003e **Note:** `\u003chostname\u003e` = your `fqdn` if defined, otherwise your server's IP address.\n  ```\n  https://\u003chostname\u003e/dhis\n  https://\u003chostname\u003e/dhis-glowroot\n  https://\u003chostname\u003e/munin\n  ```\n\n## Adding a new instance \n- Edit the inventory hosts file by running the command below and add an entry line under `[instances]`\n  category, ensure the instance name and the value of `ansible_host` (instance private IP) are unique. \n  ```\n  vim dhis2-server-tools/deploy/inventory/hosts \n  ```\n- Example\n  ```ini\n  [web]\n  proxy  ansible_host=172.19.2.2\n\n  # database servers/containers\n  [databases]\n  postgres  ansible_host=172.19.1.20\n\n  # dhis2 servers/containers\n  [instances]\n  hmis      ansible_host=172.19.2.11  database_host=postgres  dhis2_version=2.39 proxy_rewrite=True\n  training  ansible_host=172.19.2.12  database_host=postgres  dhis2_version=2.39\n  # \u003c-- add new instance here\n\n  # monitoring server/container\n  [monitoring]\n  monitor   ansible_host=172.19.2.30\n  ```\n\n- re-run the installation as explained on [Step 5 — The\n  Install](#step-5--the-install) or [Step 7: Run the\n  playbook](#step-8-run-the-playbook) depending on your deployment\n  architecture. \n\n## Using a Custom TLS Certificate \n\n- You will need to have two files, named `customssl.crt` and `customssl.key`.\u003cbr\u003e\n  `customssl.crt` should contain the main certificate concatenated with intermediate and\n   root certificates.\n-  Copy these two files into `dhis2-server-tools/deploy/roles/proxy/files/` directory, preserving their names.\n- Edit hosts file and set `TLS_TYPE=customssl`\n  ```\n  vim dhis2-server-tools/deploy/inventory/hosts\n  ```\n  ```ini\n  # Options: nginx, apache2 defaults to nginx\n  proxy=nginx\n\n  # Options: letsencrypt, customssl, default(letsencrypt)\n  SSL_TYPE=customssl\n  ```\n- re-run the installation as explained on [Step 5 — The\n  Install](#step-5--the-install) or [Step 7: Run the\n  playbook](#step-8-run-the-playbook) depending on your deployment\n  architecture. \n\n## Conclusion\nAt this point you should have DHIS2 up and running.\n\n\u003e **Note:** `\u003chostname\u003e` = your `fqdn` if defined, otherwise your server's IP address.\n\n- **DHIS2** — `https://\u003chostname\u003e/dhis`\n- **Glowroot** — `https://\u003chostname\u003e/dhis-glowroot` ([glowroot.org](https://glowroot.org/) for application performance monitoring)\n- **Munin** — `https://\u003chostname\u003e/munin` ([munin-monitoring.org](https://munin-monitoring.org/) for server resource monitoring)\n  - If you changed `munin_base_path`: `https://\u003chostname\u003e/\u003cyour_munin_base_path\u003e`\n\n\u003e **Default credentials:** Username: `admin` / Password: `district`\n\u003e\n\u003e **Important:** Change these default passwords immediately after your first login.\n\n\n## Other important links \n- [Supported variables ](./docs/Variables.md)\n- [Hosts and hosts grouping ](./docs/Inventory-Host-File.md)\n- [Optimizing PostgreSQL](./docs/Optimizing-PostgreSQL.md)\n- [LXC container management](./docs/Basic-LXC-container-Management.md)\n- [Service management with systemctl](./docs/Systemd-Service-Management.md)\n- [SSH connection](./docs/SSH-Connection.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhis2%2Fdhis2-server-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhis2%2Fdhis2-server-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhis2%2Fdhis2-server-tools/lists"}