Dab Tech Solutions
How to upgrade from dhis2-tools-ng to dhis2-tools-dab
We have previously introduced dhis2-tools-dab to the world, but many of you are wondering: how to I upgrade from the current dhis2-tools-ng to the new management system?
This article explains how you can seamlessly upgrade your dhis-tools setup to utilise the new features provided by the new suite of tools.
Prepare for the upgrade
Before upgrading, it’s good practice to make a backup of your current containers so in case something goes wrong you can easily restore them.
There are plenty of how to perform a backup and restore of LXD containers (like this one). In general, you have to:
- Backup LXD init information
- Backup all containers
- Backup LXD snap directories
There is no need to backup DHIS2 specific files since both dhis2-tools can easily restore them via install_scripts.sh script: just run it within each other’s setup directory and you will be good to go.
To be extra careful, we recommend to save all the backups in a different server in case of an emergency situation.
How to upgrade
The upgrade process will:
- Update LXD from version 4.0 to version 5.0 stable
- Install the new scripts (under
/usr/local/bin) - Check for containers in
/usr/local/etc/dhis/containers.jsonand create them if not present on the system
To start the upgrade process you need just two simple steps. Please note that no downtime is expected when upgrading.
- Download dhis2-tools-dab
dab@battlechine:~$ git clone https://github.com/davinerd/dhis2-tools-dab.git
dab@battlechine:~$ cd dhis2-tools-dab/setup- Run the
lxd_setup.shscript (assuming defaults inparse_config.sh):
dab@battlechine:~/dhis2-tools-dab/setup$ sudo ./lxd_setup.sh
[sudo] password for dab:
[2023-02-14 13:40:37] [INFO] [lxd_setup.sh] Updating local machine
Hit:1 http://es.archive.ubuntu.com/ubuntu jammy InRelease
Hit:2 http://packages.microsoft.com/repos/code stable InRelease
Get:3 http://es.archive.ubuntu.com/ubuntu jammy-updates InRelease [119 kB]
Hit:4 https://repo.protonvpn.com/debian stable InRelease
Hit:5 https://dl.google.com/linux/chrome/deb stable InRelease
Get:6 http://es.archive.ubuntu.com/ubuntu jammy-backports InRelease [107 kB]
Get:7 http://security.ubuntu.com/ubuntu jammy-security InRelease [110 kB]
Hit:9 https://updates.signal.org/desktop/apt xenial InRelease
Hit:10 https://apt.syncthing.net syncthing InRelease
Get:8 https://packages.cloud.google.com/apt kubernetes-xenial InRelease [8.993 B]
Err:8 https://packages.cloud.google.com/apt kubernetes-xenial InRelease
The following signatures couldn't be verified because the public key is not available: NO_PUBKEY B53DC80D13EDEF05
Get:12 http://security.ubuntu.com/ubuntu jammy-security/main amd64 DEP-11 Metadata [41,4 kB]
Get:13 http://security.ubuntu.com/ubuntu jammy-security/universe amd64 DEP-11 Metadata [13,3 kB]
Hit:11 https://packagecloud.io/slacktechnologies/slack/debian jessie InRelease
Fetched 400 kB in 2s (165 kB/s)
Reading package lists... Done
W: An error occurred during the signature verification. The repository is not updated and the previous index files will be used. GPG error: https://packages.cloud.google.com/apt kubernetes-xenial InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY B53DC80D13EDEF05
W: https://packagecloud.io/slacktechnologies/slack/debian/dists/jessie/InRelease: Key is stored in legacy trusted.gpg keyring (/etc/apt/trusted.gpg), see the DEPRECATION section in apt-key(8) for details.
W: Failed to fetch https://apt.kubernetes.io/dists/kubernetes-xenial/InRelease The following signatures couldn't be verified because the public key is not available: NO_PUBKEY B53DC80D13EDEF05
W: Some index files failed to download. They have been ignored, or old ones used instead.
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Calculating upgrade... Done
The following packages were automatically installed and are no longer required:
libllvm13 linux-tools-common
Use 'sudo apt autoremove' to remove them.
The following packages have been kept back:
alsa-ucm-conf python3-software-properties software-properties-common software-properties-gtk ubuntu-advantage-tools update-notifier update-notifier-common
0 upgraded, 0 newly installed, 0 to remove and 7 not upgraded.
[2023-02-14 13:40:47] [INFO] [lxd_setup.sh] Installing/Updating lxd to 5.0/stable
2023-02-14T13:41:17+01:00 INFO Waiting for "snap.lxd.daemon.service" to stop.
lxd (5.0/stable) 5.0.2-838e1b2 from Canonical✓ refreshed
[2023-02-14 13:41:30] [INFO] [lxd_setup.sh] Initializing lxd
Skipping adding existing rule
Skipping adding existing rule (v6)
Skipping adding existing rule
Skipping adding existing rule (v6)
Skipping adding existing rule
Skipping adding existing rule (v6)
Skipping adding existing rule
Skipping adding existing rule (v6)
Installing service scripts
DHIS2 cron already exists
Installing new configuration files
'etc/dhis2-env' -> '/usr/local/etc/dhis/dhis2-env'
'etc/filebeat.yml' -> '/usr/local/etc/dhis/filebeat.yml'
'etc/log4j2-file.xml' -> '/usr/local/etc/dhis/log4j2-file.xml'
'etc/log4j2.xml' -> '/usr/local/etc/dhis/log4j2.xml'
'etc/proxy_params' -> '/usr/local/etc/dhis/proxy_params'
'etc/s3cfg' -> '/usr/local/etc/dhis/s3cfg'
'etc/tomcat_default' -> '/usr/local/etc/dhis/tomcat_default'
'etc/tomcat_setup' -> '/usr/local/etc/dhis/tomcat_setup'
'etc/tomcat-users.xml' -> '/usr/local/etc/dhis/tomcat-users.xml'
Credentials file already exists, not over-writing
containers.json already exists, not over-writing
Done
Skipping adding existing rule
Skipping adding existing rule (v6)
Skipping adding existing rule
Skipping adding existing rule (v6)
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
auditd is already the newest version (1:3.0.7-1build1).
jq is already the newest version (1.6-2.1ubuntu3).
apache2-utils is already the newest version (2.4.52-1ubuntu4.3).
unzip is already the newest version (6.0-26ubuntu3.1).
The following packages were automatically installed and are no longer required:
libllvm13 linux-tools-common
Use 'sudo apt autoremove' to remove them.
0 upgraded, 0 newly installed, 0 to remove and 7 not upgraded.
[2023-02-14 13:41:35] [WARN] [lxd_setup.sh] Container proxy already exist, skipping
[2023-02-14 13:41:35] [WARN] [lxd_setup.sh] Container postgres already exist, skipping
[2023-02-14 13:41:36] [WARN] [lxd_setup.sh] Container monitor already exist, skipping
[2023-02-14 13:41:36] [INFO] [lxd_setup.sh] Adding containers to monitor...
[2023-02-14 13:41:36] [INFO] [lxd_setup.sh] Installing munin into container 'proxy'
Reading package lists... Done
Building dependency tree
Reading state information... Done
munin-node is already the newest version (2.0.56-1ubuntu1).
The following package was automatically installed and is no longer required:
libfreetype6
Use 'apt autoremove' to remove it.
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
Skipping adding existing rule
[2023-02-14 13:41:38] [WARN] [lxd_setup.sh] Container proxy already added to monitor. Skipping
[2023-02-14 13:41:38] [INFO] [lxd_setup.sh] Installing munin into container 'postgres'
Reading package lists... Done
Building dependency tree
Reading state information... Done
munin-node is already the newest version (2.0.56-1ubuntu1).
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
Skipping adding existing rule
[2023-02-14 13:41:41] [WARN] [lxd_setup.sh] Container postgres already added to monitor. Skipping
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
munin-node is already the newest version (2.0.57-1ubuntu2).
The following packages were automatically installed and are no longer required:
libllvm13 linux-tools-common
Use 'sudo apt autoremove' to remove them.
0 upgraded, 0 newly installed, 0 to remove and 7 not upgraded.
dab@battlechine:~/dhis2-tools-dab/setup$That’s it! You have successfully upgraded to dhis2-tools-dab.
To verify:
dab@battlechine:~/dhis2-tools-dab/setup$ lxc --vesion
5.0.2
dab@battlechine:~/dhis2-tools-dab/setup$ lxc list
+----------+---------+---------------------+------+-----------+-----------+
| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS |
+----------+---------+---------------------+------+-----------+-----------+
| monitor | RUNNING | 192.168.0.30 (eth0) | | CONTAINER | 0 |
+----------+---------+---------------------+------+-----------+-----------+
| postgres | RUNNING | 192.168.0.20 (eth0) | | CONTAINER | 0 |
+----------+---------+---------------------+------+-----------+-----------+
| proxy | RUNNING | 192.168.0.2 (eth0) | | CONTAINER | 0 |
+----------+---------+---------------------+------+-----------+-----------+Post-upgrade steps
After you’ve upgraded, you can now take advantage of the new features.
First, you may want to start securing your services.
By default, with dhis2-tools-ng, munin and glowroot are installed without authentication: this means both services are exposed publicly to the internet for anyone to access.
dhis2-tools-dab has borrowed from SolidLines a tool called dhis2-set-credential and expanded it to be an easy credentials management tool.
To secure current munin installation:
dab@battlechine:~/dhis2-tools-dab/setup$ sudo dhis2-set-credential munin monitor
[2023-02-14 13:43:13] [INFO] [dhis2-set-credential] Service munin found. Setting credentials
==============================
Do you want to add the password manually for the user admin in the service munin? (If not, password will be generated randomly)
1) Yes
2) No
#? 2
Adding password for user admin
Credentials have been set
=========================
Service: monitor (munin)
Username: admin
Password: 948586b9ba9e5b24d62cbcc3a0ea5e1c0ad26ef1f9a41004
dab@battlechine:~/dhis2-tools-dab/setup$And here it is the result:
To secure running glowroot installation on a DHIS2 instance called testdev we will use a very similar command but this time the service name will be glowroot :
dab@battlechine:~/dhis2-tools-dab/setup$ sudo dhis2-set-credential glowroot testdev
[2023-02-14 13:55:56] [INFO] [dhis2-set-credential] Service glowroot found. Setting credentials
==============================
Do you want to add the password manually for the user admin in the service glowroot? (If not, password will be generated randomly)
1) Yes
2) No
#? 2
--2023-02-14 13:55:57-- https://github.com/glowroot/glowroot/releases/download/v0.13.6/glowroot-central-0.13.6-dist.zip
Resolving github.com (github.com)... 140.82.121.3
Connecting to github.com (github.com)|140.82.121.3|:443... connected.
HTTP request sent, awaiting response... 302 Found
Location: https://objects.githubusercontent.com/github-production-release-asset-2e65be/16336212/40f7f480-5b29-11ea-937a-fecb3d456fb2?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20230214%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230214T125558Z&X-Amz-Expires=300&X-Amz-Signature=d930680b96e5efcf2a1a3aca1f26500def56d81e414965dfe6950a9ef16c800d&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=16336212&response-content-disposition=attachment%3B%20filename%3Dglowroot-central-0.13.6-dist.zip&response-content-type=application%2Foctet-stream [following]
--2023-02-14 13:55:58-- https://objects.githubusercontent.com/github-production-release-asset-2e65be/16336212/40f7f480-5b29-11ea-937a-fecb3d456fb2?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20230214%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230214T125558Z&X-Amz-Expires=300&X-Amz-Signature=d930680b96e5efcf2a1a3aca1f26500def56d81e414965dfe6950a9ef16c800d&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=16336212&response-content-disposition=attachment%3B%20filename%3Dglowroot-central-0.13.6-dist.zip&response-content-type=application%2Foctet-stream
Resolving objects.githubusercontent.com (objects.githubusercontent.com)... 185.199.108.133, 185.199.110.133, 185.199.111.133, ...
Connecting to objects.githubusercontent.com (objects.githubusercontent.com)|185.199.108.133|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 46193863 (44M) [application/octet-stream]
Saving to: ‘/tmp/tmp.7OwfqPfKDh/glowroot-central-0.13.6-dist.zip’
glowroot-central-0.13.6-dist.zip 100%[=====================================================================================================>] 44.05M 4.83MB/s in 9.8s
2023-02-14 13:56:08 (4.50 MB/s) - ‘/tmp/tmp.7OwfqPfKDh/glowroot-central-0.13.6-dist.zip’ saved [46193863/46193863]
[2023-02-14 13:56:11] [INFO] [dhis2-set-credential] Glowroot credentials set. Restarting tomcat
Credentials have been set:
=========================
Instance: testdev
Service: testdev-glowroot
Username: admin
Password: b61f42699783a4c6eee444e99d5ea5450e34c8bfa85d0fd6
dab@battlechine:~/dhis2-tools-dab/setup$Pointing to glowroot, it now asks for credentials:
Default DHIS2 installation comes with a built in admin account with an hardcoded password ( district). dhis2-set-credential can be used to set a different, more robust DHIS2’s admin password and can be scripted to rotate the password regularly:
$ sudo dhis2-set-credential dhis2-admin testdev
[2023-02-14 14:00:18] [INFO] [dhis2-set-credential] Service dhis2-admin found. Setting credentials
==============================
Do you want to add the password manually for the user admin in the service dhis2-admin? (If not, password will be generated randomly)
1) Yes
2) No
#? 2
{"httpStatus":"OK","httpStatusCode":200,"status":"OK","response":{"responseType":"ImportReport","status":"OK","stats":{"created":0,"updated":1,"deleted":0,"ignored":0,"total":1},"typeReports":[{"klass":"org.hisp.dhis.user.User","stats":{"created":0,"updated":1,"deleted":0,"ignored":0,"total":1},"objectReports":[{"klass":"org.hisp.dhis.user.User","index":0,"uid":"M5zQapPyTZI","errorReports":[]}]}]}}
Credentials have been set:
=========================
Instance: testdev
Service: testdev-dhis2-admin
Username: admin
Password: 6fT8#t{tJ=D<oG*!>8ve7J%x
$Now should not be able to login with the default district password and use the one reported above instead.
For details on how the tool works and all its features, please refer to the official documentation.
Please note that changing password for DHIS2 via dhis2-set-credential works for the first time only if the default admin password hasn’t been changed. If you did, you have to save the new password into the dhis2-tools-dab keystore via the save_creds function within libs.sh file to being able to manage credentials with the tool:
dab@battlechine:~/dhis2-tools-dab/setup$ source libs.sh
dab@battlechine:~/dhis2-tools-dab/setup$ save_creds '{"service":"testdev-dhis2-admin","username":"admin","password":"very secure password!"}'
dab@battlechine:~/dhis2-tools-dab/setup$ sudo dhis2-set-credential dhis2-admin testdev
[2023-02-15 11:05:43] [INFO] [dhis2-set-credential] Service dhis2-admin found. Setting credentials
==============================
Do you want to add the password manually for the user admin in the service dhis2-admin? (If not, password will be generated randomly)
1) Yes
2) No
#? 2
{"httpStatus":"OK","httpStatusCode":200,"status":"OK","response":{"responseType":"ImportReport","status":"OK","stats":{"created":0,"updated":1,"deleted":0,"ignored":0,"total":1},"typeReports":[{"klass":"org.hisp.dhis.user.User","stats":{"created":0,"updated":1,"deleted":0,"ignored":0,"total":1},"objectReports":[{"klass":"org.hisp.dhis.user.User","index":0,"uid":"M5zQapPyTZI","errorReports":[]}]}]}}
Credentials have been set:
=========================
Instance: testdev
Service: testdev-dhis2-admin
Username: admin
Password: #,y8f0?W_jnnyiI=LEZ<BS2c
dab@battlechine:~/dhis2-tools-dab/setup$If you want to retrieve credentials for any service, you can do in two ways (in the following example we are retrieving munin credentials):
# using get_creds
dab@battlechine:~/dhis2-tools-dab/setup$ source libs.sh
dab@battlechine:~/dhis2-tools-dab/setup$ get_creds "munin"
{ "service": "munin", "username": "admin", "password": "638f70dabb638aed8edb0d65" }
# using jq
dab@battlechine:~/dhis2-tools-dab/setup$ sudo cat /usr/local/etc/dhis/.credentials.json | jq -r '.credentials[] | select(.service=="munin")'
{
"service": "munin",
"username": "admin",
"password": "638f70dabb638aed8edb0d65"
}
dab@battlechine:~/dhis2-tools-dab/setup$Final thoughts
There are plenty of new features to discover. For details, please refer to the extended services documentation. We will add more information so it can become a useful reference.
We are also thinking about adding new features. Interested in helping us out? If so, read the contributing section and start giving your contribution!
Stay tuned for more in depths tutorials on dhis2-tools-dab.
Need help with the migration? Contact us at info@dab.solutions and we will get in touch to support you in performing a safe migration.
EN 
ES