Update

Ansible-based update on Linux

1. Update MiaRec playbooks

From time to time, we update playbooks for MiaRec installation/update. It doesn't occur with every software release, but sometimes we introduce new features to our product, that require update of installation scripts as well.

The MiaRec Ansible playbooks are hosted on public GitHub repository. To see if there were any changes to the playbooks, you can check the commit history.

Note, it will not harm to execute below commands even if there were no any changes to playbooks.

To load the latest version of playbooks, execute the following command on the Ansible controller machine:

cd /opt/ansible-miarec
git pull
git submodule update -i --recursive

Explanation:

  • git pull command will load the latest version of the top project
  • git submodule update ... command will load the latest version of the sub-projects (submodules).

If you see the error "Your local changes to the following files would be overwritten by merge", then some of local files have been edited manually on your server and the same files have been updated in the MiaRec github repository. You can run git diff command to see exactly what changes were made to the local files. To revert changes, you can execute command git checkout -- FILE_NAME. Where, FILE_NAME is the name of the file to revert changes.

Then try again to pull the latest version from the MiaRec repository.

2. Update the MiaRec version info in the inventory file

On the Ansible controller machine, edit the version info in the inventory file /opt/ansible-miarec/hosts.

Example of this file:

[all:vars]
; -------------------------------
; Version of installed packages
; -------------------------------
miarecweb_version   = 6.0.0.370
miarec_version      = 6.0.0.31
miarec_screen_version = 1.1.0.17 

The latest MiaRec version info is available at Download page.

3. Run playbook

To update MiaRec, run the following command:

cd /opt/ansible-miarec

ansible-playbook -i hosts setup-miarec.yml

When using password authentication, then add --ask-pass to the above command, like:

ansible-playbook -i hosts setup-miarec.yml --ask-pass

Confirm satisfactory completion with zero items unreachable or failed:

PLAY RECAP ********************************************************************
...
miarec                :  ok=38   changed=25   unreachable=0    failed=0

Resolve issue "Upgrade is stuck at the task Upgrade database layout"

If the upgrade process is stuck at the task "Upgrade database layout" for too long (more than 15 minutes), then do the following:

  1. Terminate the upgrade process (Ctrl+C)

  2. Stop gracefully all celery jobs (“gracefull” means that celery deamon will be stopped when all scheduled jobs complete their execution):

    service celeryd stop
    service celerybeat stop
    
  3. Stop Apache web server:

    service httpd stop
    
  4. Re-run Ansible upgrade playbook:

    ansible-playbook -i hosts setup-miarec.yml
    
  5. The Celery and Apache services should be started automatically as a part of Ansible upgrade process.

    service celeryd start
    service celerybeat start
    service httpd start
    

Why the upgrade process may stuck at the task "Upgrade database layout"?

We continuously add new features to our product. Some features require changes to database layout, like add column, table, etc. Some changes to database layout may require an exclusive lock on affected tables. The upgrade process may stuck waiting for a lock to be acquired. If other services are actively accessing database, it may take too long to acquire the lock.

Note, above instructions instruct how to stop web server and celery services only. The recording service doesn't have to be stopped. It continues to record calls even when web server and/or celery services are down. The recorder service also accesses the database, but it does not prevent acquiring a lock on table because recorder doesn't use transactions.

Migrate from manual to Ansible-based setup

This guide provide instructions for migration of manually-installed MiaRec software to Ansible-based setup.

Why migrate?

  • It simplifies future updates. Ansible-based installation/update is a lot simpler. Basically, you can update software in one command.
  • Manual installation is deprecated. New features will be supported in Ansible-based setup only as it is easier to maintain various distributives (Centos/RedHat/Ubuntu) and their versions using a single Ansible playbook. Manual installation is also error-prone as it requires manual copy/paste of many commands.

Note, this guide assumes all-in-one setup of MiaRec, i.e. all components (database, recorder, web server) are installed on the same host. Ansible playbooks will be run from the same host (although it is possible to run playbook from a remote host).

Installation overview

  1. Install Python 2.7 (required for Centos 6)
  2. Install Ansible
  3. Download the MiaRec ansible playbooks
  4. Check existing versions of PostgreSQL and Python
  5. Create inventory file (hosts)
  6. Run setup-miarec.yml playbook to update MiaRec software

1. Install Python 2.7 (required for Centos 6 only)

This step is required for Centos 6 only as it has old version of Python 2.6. Skip this step if you are using Centos 7 or Ubuntu Server.

Verify if Python 2.7 is available on the server using the following commands:

$ which python2.7
/usr/local/bin/python2.7

$ python2.7 --version
Python 2.7.12

If Python 2.7 is installed (as shown above), then skip this step. Otherwise, install Python 2.7.

Centos 6 comes pre-installed with older version of Python (2.6). Ansible doesn't work on such old version.

We are not going to replace the older version of Python with newer. Instead, the newer version will be installed in parallel. A system-default Python will remain the same (if you call python --version, you still see version 2.6), but new version will be available by calling the exact name python2.7 --version.

Install the required packages for building python:

yum install zlib-devel bzip2-devel xz-devel openssl-devel sqlite-devel expat-devel

Download the latest stable Python 2.7 source code files from https://www.python.org/downloads/source/:

wget https://www.python.org/ftp/python/2.7.14/Python-2.7.14.tgz

Extract source code:

tar -xzvf Python-2.7.14.tgz

Build Python binaries:

cd Python-2.7.14
./configure --prefix=/usr/local --enable-shared LDFLAGS="-Wl,-rpath /usr/local/lib"
make

Install Python using alternative installation option (altinstall). Normally, one would use “make install”; however, in order not to override system defaults - replacing the Python already used by the system - we will use make altinstall.

make altinstall

This will install python into /usr/local/bin with name, which contains version, like /usr/local/bin/python2.7.

2. Install Ansible on Centos 6/7

Download PIP installer script and run it (PIP is a tool for installing Python packages. Ansible is written in Python):

wget https://bootstrap.pypa.io/get-pip.py
python2.7 get-pip.py

Install Ansible using PIP:

pip2.7 install "ansible<2.7" 

Verify Ansible version:

ansible --version

The output should be something like:

$ ansible --version
ansible 2.3.1.0
  config file = 
  configured module search path = Default w/o overrides
  python version = 2.7.14 (default, Nov 19 2016, 06:48:10) [GCC 5.4.0 20160609]

Verify that ansible version is 2.2+ or higher and python version is 2.7. If the python version shows 3.x then the installation of Ansible is not correct. Contact the MiaRec representative for support.

2. Install Ansible on Ubuntu

Update package source lists:

sudo apt-get update

Install PIP (a tool for installing Python packages. Ansible is written in Python):

sudo apt-get install python-dev python-pip

Install Ansible using PIP:

sudo pip install ansible 

Verify Ansible version:

ansible --version

The output should be something like:

$ ansible --version
ansible 2.3.1.0
  config file = 
  configured module search path = Default w/o overrides
  python version = 2.7.12 (default, Nov 19 2016, 06:48:10) [GCC 5.4.0 20160609]

Verify that ansible version is 2.2+ or higher and python version is 2.7. If the python version shows 3.x then the installation of Ansible is not correct. Contact the MiaRec representative for support.

3. Download the MiaRec ansible playbooks

Clone the latest stable release of the MiaRec-Ansible Git repository in the /opt/ansible-miarec directory:

yum install git

git clone --recursive https://github.com/miarec/ansible-miarec /opt/ansible-miarec

If you receive HTTP failed error, then run yum install nss to update the root SSL certificates on your server.

4. Check existing versions of PostgreSQL and Python

Navigate in MiaRec web interface to Administration -> Maintenance -> Version and notice the versions of PostreSQL database and Python. In our example, PostgreSQL version is 9.4.8 and Python is 3.4.3.

MiaRec version

Alternatively, you can execute the following commands in console:

$ psql --version
psql (PostgreSQL) 9.4.8


$ python3.4 --version
Python 3.4.3

Most likely, Python 3.4.3 has been installed manually on this server. Note, this Python version (3.4.3) is different from the Python version 2.7 discussed above for Ansible. MiaRec software requires 3.4+, but Ansible requires 2.7. It is ok to have multiple version of Python on the same machine as long as they are installed into different directories using make altinstall command.

5. Create inventory file (hosts)

The Ansible inventory file is an INI-formatted file that defines the hosts and groups of hosts upon which commands, modules, and tasks in playbooks operate (the Inventory File is highly configurable, see the Ansible documentation for more information). This guide assumes that there is only one host (all-in-one setup).

First, check the latest release information at Download MiaRec and edit the following variables in the hosts file (discussed later):

  • miarec_version
  • miarecweb_version
  • miarec_screen_version

Create /opt/ansible-miarec/hosts file:

vim /opt/ansible-miarec/hosts

Copy/paste the following content for the hosts file. Make sure postgresql_version and python_version variables are set to the previously identified versions. Note, the PostgreSQL version should be specified in short format x.x, but Python should be specified in full format x.x.x.

[all]
; ---------------------------------
; All-in-one host
; Parameters:
;   - private_ip_address => ip address to access the host from other components
; (for example, web application needs to connecto to database)
; ---------------------------------

miarec ansible_connection=local private_ip_address=127.0.0.1


[all:vars]
; -------------------------------
; Version of installed packages
; -------------------------------
miarecweb_version   = 6.0.0.xxx
miarec_version      = 6.0.0.xxx
miarec_screen_version = 1.1.0.xxx
postgresql_version  = 9.4
python_version      = 3.4.3


[recorder]
miarec

[screen]
miarec

[db]
miarec

[redis]
miarec

[web]
miarec

[celery]
miarec

[celerybeat]
miarec

6. Run setup-miarec.yml playbook to update MiaRec software

The playbook setup-miarec.yml will install/update the MiaRec software components (recorder, web portal and screen recorder).

cd /opt/ansible-miarec

ansible-playbook setup-miarec.yml

Confirm satisfactory completion with zero items unreachable or failed:

PLAY RECAP ********************************************************************
...
miarec                :  ok=38   changed=25   unreachable=0    failed=0

Verify MiaRec operation

Verify MiaRec after update