Ansible is a tool used to automate software provisioning, configuration management, and application deployment. It offers several advantages over other IT automation tools similar to it; It's minimal in nature, you don't need to install anything on the servers you're deploying to (except Python 2).
...
To easily manage (deploy new instances of or update) your OpenSRP, Keycloak, OpenMRS, and DHIS2 servers you would require Ansible to automate the deployment process. Therefore the opensrp-playbooks provided here are meant to facilitate the process. All you need to do is clone the opensrp-playboks repository and then define your inventories based on your DevOps clients and development environments(staging, production or preview) and then run the playbooks to install the servers. The repository uses Ansible's recommended alternative directory layout.
For local "dev" deployments, you will need to install Virtualbox. You'll as well need the vault password used to encrypt sensitive info inside the sample inventory available in the repo. You will also need to create host_vars and group_vars to match your setup.
...
Create an sudo user (user with admin rights) called ubuntu and ensure that the user has NOPASSWDconfig on the `/etc/sudoers` (you can refer to the command used below on Vagrant #3).
On the host you have to install openssh-server to enable ssh connections and make it possible to ssh using the root account otherwise you will need an account with administrative privileges to run the playbooks.
On Ubuntu or any debian disto you can install it using this command
Code Block $ sudo apt install openssh-server
Finally ensure you can access the server though ssh ubuntu@vm-ip-address (You can get the
vm-ip-address
of the VM by runningifconfig
on the host terminal). If it requests for password kindly disable it byCode Block $ sudo sed -i 's/prohibit-password/yes/' /etc/ssh/sshd_config $ sudo service ssh restart
Vagrant:
Vagrant is a tool for building and managing virtual machine environments in a single workflow. You can download it from here. Below is a Vagrantfile
that can get you up and running.
Code Block |
---|
# -*- mode: ruby -*- # vi: set ft=ruby : # All Vagrant configuration is done below. The "2" in Vagrant.configure # configures the configuration version (we support older styles for # backwards compatibility). Please don't change it unless you know what # you're doing. Vagrant.configure("2") do |config| config.vm.box = "hashicorp/bionic64" config.vm.network "private_network", ip: "192.168.33.13" #replace with any private ip available config.vm.provision "shell", inline: <<-SHELL apt-get update apt-get install -y cloud-init python3 python3-psycopg2 useradd -s /bin/bash -m -p $(openssl passwd -1 <specify-password-for-ubuntu-user>) ubuntu #1 usermod -s /bin/bash -aG sudo ubuntu #2 sudo sed -i -e '$a\\ubuntu ALL=(ALL) NOPASSWD:ALL' /etc/sudoers #3 SHELL end |
...
Git clone the opensrp-playbooks from this link OpenSrp playbooks. Then switch directory to opensrp-playbooks you just cloned.
Code Block $ git clone --recursive git@github.com:opensrp/playbooks.git && cd playbooks
Setup a python virtual environment:
Kindly follow the steps here.
Create a virtual environment called
opensrp
.Switch to
opensrp
environment by typing:Code Block $ workon opensrp
Add the following line to the end of
~/.bashrc
of your machine ... Ensure you update <python-version> with version of python running on you machine.Code Block export ANSIBLE_STRATEGY_PLUGINS=~/.virtualenvs/opensrp/lib/python<python-version>/site-packages/ansible_mitogen/plugins/strategy #Update <python-version>
Run the following command while on the virtual environment
Code Block $ python --version
confirm that your active python version is 3
Code Block $ pip install -r requirements/base.pip
Code Block $ ansible-galaxy role install -r requirements/ansible-galaxy.yml -p ~/.ansible/roles/opensrp
Code Block $ ansible-galaxy collection install -r requirements/ansible-galaxy.yml -p ~/.ansible/collections/opensrp
Opensrp-playbooks requires some modules from ansible-galaxy. The modules are specified in the requirements.yml file. Refer to this link for more information on ansible-galaxy : ansible-galaxy documentation
You need to run the two commands above before running any playbooks to install the required modules..
If you have not created the inventory yet kindly execute the commands below on the root of opensrp-playbooks directory.
$ ./scripts/new_inventory.sh opensrp-app-servers demo staging
Code Block $ ./scripts/new_inventory.sh opensrp-app-servers demo staging
$ ./scripts/new_inventory.sh openmrs-app-servers demo staging (optional if keycloak is used)
Code Block $ ./scripts/new_inventory.sh openmrs-app-servers demo staging
$ ./scripts/new_inventory.sh mysql demo staging
Code Block $ ./scripts/new_inventory.sh mysql demo staging
$ ./scripts/new_inventory.sh all demo staging
Code Block $ ./scripts/new_inventory.sh all demo staging
$ ./scripts/new_inventory.sh opensrp-redis-servers demo staging
Code Block $ ./scripts/new_inventory.sh opensrp-redis-servers demo staging
$ ./scripts/new_inventory.sh opensrp-postgresql-servers demo staging
Code Block $ ./scripts/new_inventory.sh opensrp-postgresql-servers demo staging
$ ./scripts/new_inventory.sh keycloak-app-servers demo staging (optional if openmrs is used)
Code Block $ ./scripts/new_inventory.sh keycloak-app-servers demo staging
Add the
host_vars
directory andhosts
file from the following directory: sample-inventories/inventory-aUpdate the
host_vars
vars.yml file with your VMs ip, as below:ansible_host: "<vm-ip-address>"
Finally add files directory with a pgp directory containing gpg keys like so:
...
Code Block | ||
---|---|---|
| ||
$ ansible-playbook -i inventories/demo/staging setup-server.yml --vault-password-file=[local path to the file holding the vault password] --skip-tag nginx,certbot |
...
OpenMRS (for opensrp server web v2.1.*)
You will need the following for you local stage setup :
on inventories/demo/staging/group_vars/opensrpopenmrs-app-servers/vars.yml
Code Block |
---|
# Update these if you have a domain to use. opensrpopenmrs_certsnginx_fromenabled_letsencryptsites: false[] opensrpopenmrs_nginx_sites: [] opensrpcerts_nginxfrom_enabled_sitesletsencrypt: [] # end opensrp_install_swapfalse openmrs_certs_from_letsencrypt: false # update with the opensrp version tag/branch you need to deploy opensrp_version: "v2.1" |
Code Block |
---|
# for opensrp_version version v2.2 you have to add the below
opensrp_maven_package_profiles:
- postgres
- jedis
- oauth2 |
Code Block |
---|
# keycloak configs
opensrp_keycloak_realm: "realm"
opensrp_keycloak_auth_server_url: "http://keycloak.local/auth/"
opensrp_keycloak_client: "resource-id"
opensrp_keycloak_client_secret: "234324" |
...
openmrs_tomcat_version: 9
tomcat_group: "tomcat" |
on inventories/demo/staging/group_vars/mysql/vars.yml
Code Block |
---|
mysql_backup_gpg_dir: "{{ all_gpg_dir }}" |
Run the following command to start the OpenMRS playbook in your local staging environment:
Code Block |
---|
$ ansible-playbook -i inventories/demo/staging deploy-openmrs.yml --vault-password-file=[local path to the file holding the vault password] --skip-tag nginx |
Keycloak (for opensrp server web v2.2.* and above)
Run the following command to start the keycloak playbook in your local staging environment: (ensure keycloak-app-servers
is in your hosts file )
Code Block |
---|
$ ansible-playbook -i inventories/demo/staging deploy-keycloak.yml --vault-password-file=[local path to the file holding the vault password] --skip-tag nginx |
OpenSRP
You will need the following for you local stage setup:
on inventories/demo/staging/group_vars/opensrp-app-servers/vars.yml
Code Block |
---|
# Update these if you have a domain to use. opensrp_postgrescerts_enablefrom_sslletsencrypt: false postgresqlopensrp_enablenginx_sslsites: false[] postgresqlopensrp_backupnginx_enabled_sites: false |
In opensrp we have spring maven profiles, kindly enable the ones you need:
The defaults are:
- postgres
- jedis
- basic_auth # this can be replaced with oauth2 to use keycloak or spring authentication server with openmrsThe other available profiles are openmrs-sync, dhis2-sync, rabbitmq, rapidpro, lettuce, dhis2-sync-vaccine-tracker and more
To use Openmrs one has to use v2.1* tags.
Run the following command to start the OpenSRP playbook in your local staging environment:
Code Block |
---|
$ ansible-playbook -i inventories/demo/staging deploy-opensrp.yml --vault-password-file=[local path to the file holding the vault password] --skip-tag nginx |
OpenMRS
You will need the following for you local stage setup
on inventories/demo/staging/group_vars/openmrs-app-servers/vars.yml
Code Block |
---|
# Update these if you have a domain to use. openmrs_nginx_enabled_sites: [] openmrs_nginx_sites: [] certs_from_letsencrypt: false openmrs_certs_from_letsencrypt: false # openmrs_tomcat_version: 9 tomcat_group: "tomcat[] # end opensrp_install_swap: false # update with the opensrp version tag/branch you need to deploy opensrp_version: "v2.1" |
Code Block |
---|
# for opensrp_version version v2.2 you have to add the below
opensrp_maven_package_profiles:
- postgres
- jedis
- oauth2 |
Code Block |
---|
# keycloak configs
opensrp_keycloak_realm: "realm"
opensrp_keycloak_auth_server_url: "http://keycloak.local/auth/"
opensrp_keycloak_client: "resource-id"
opensrp_keycloak_client_secret: "234324" |
on inventories/demo/staging/group_vars/mysqlopensrp-postgresql-servers/vars.yml
Code Block |
---|
mysql_backup_gpg_dir: "{{ all_gpg_dir }}" |
Run the following command to start the OpenMRS playbook in your local staging environment:
Code Block |
---|
$ ansible-playbook -i inventories/demo/staging deploy-openmrs.yml --vault-password-file=[local path to the file holding the vault password] --skip-tag nginx |
...
opensrp_postgres_enable_ssl: false
postgresql_enable_ssl: false
postgresql_backup_enabled: false |
In opensrp we have spring maven profiles, kindly enable the ones you need:
The defaults are:
- postgres
- jedis
- basic_auth # this can be replaced with oauth2 to use keycloak or spring authentication server with openmrsThe other available profiles are openmrs-sync, dhis2-sync, rabbitmq, rapidpro, lettuce, dhis2-sync-vaccine-tracker and more
To use Openmrs one has to use v2.1* tags.
Run the following command to start the DHIS OpenSRP playbook in your local staging environment:
Code Block |
---|
$ ansible-playbook -i inventoriesi inventories/demo/staging deploy-dhisopensrp.yml --vault-password-file=[local path to the file holding the vault password] |
...
--skip-tag nginx |
DHIS 2
Run the following command to start the DHIS playbook in your local staging environment: (ensure keycloak-app-servers
is in your hosts file )
Code Block |
---|
$ ansible-playbook -i inventories/demo/staging deploy-keycloakdhis.yml --vault-password-file=[local path to the file holding the vault password] --skip-tag nginx |
NOTE
When running the playbooks with a user other than root since ssh using root account is not recommended you need to add this extra option
--extra-vars='ansible_become_pass=youruserpassword'
...