Upgrade

Note

Upgrades of OKA are only supported between 2 consecutive minor versions, or latest minor to next major. Within a minor version, upgrade to any patch version is supported.

For example:

if you have version X.Y.Z (e.g., 1.10.0) , you cannot upgrade to version X.(Y+2).Z’ (e.g., 1.12.1) but you can upgrade to X.(Y+1).Z’ (e.g., 1.11.3)
if 1.15.5 is the latest minor version of major version 1, then you can upgrade to (X+1).0.Z’ (e.g., 2.0.3)

Warning

OKA update might take several hours depending on the size of your ElasticSearch database. We recommend to execute the installer in a screen (or similar tools such as tmux) to avoid untimely deconnections during the installation.

To upgrade OKA:

First stop OKA services: sudo systemctl stop oka.service.

Then backup the databases:

The upgrade process will also update Elasticsearch and PostgreSQL databases content. Follow below instructions to backup your databases.

Finally, proceed with the update using your latest oka-x.y.z.run.

Important

If your license was also upgraded to include some other part of the OKA Suite you might need to run an internal update to setup the new plugins. Please follow the instruction available here: Upgrading license

Elasticsearch

Backup

First, ensure that Elasticsearch database is running and accessible .
Backup your Elasticsearch database. To learn more about Elasticsearch snapshots see How to create a snapshot. Note: the snapshots are incremental, so not all the data are saved during each snapshot/backup process.
You must configure your snapshot directory before trying to take a snapshot for the first time:
Grant read/write access to the directory for Elasticsearch to store snapshots:
sudo chown elasticsearch: <BACKUP_DIR_PATH>/backup_repo
Add this line in /etc/elasticsearch/elasticsearch.yml:
path.repo: /dir_path/backup_repo
Restart Elasticsearch:
sudo systemctl restart elasticsearch
Query Elasticsearch to create a snapshot directory (in our case it will be <BACKUP_DIR_PATH>/backup_repo), this directory does not need to exist beforehand, Elasticsearch will create it automatically. You can replace my_backup by the name you want:
curl -X PUT "host:port/_snapshot/my_backup" -H 'Content-Type: application/json' -d '
{
"type": "fs",
"settings": {
      "location": "<BACKUP_DIR_PATH>/backup_repo",
      "compress": "true"
}
}'
Backup your Elasticsearch database (take a snapshot). We recommend that you create a snapshot with a name that includes the current date (see below example with $(date +%Y%m%d)). The wait_for_completion=true option will make the command synchronous: it will wait until the backup has been completed:
curl -X PUT "http://host:port/_snapshot/my_backup/snapshot_oka_$(date +%Y%m%d)?wait_for_completion=true" -H 'Content-Type: application/json' -d '
{
      "ignore_unavailable": true,
      "include_global_state": true,
      "metadata": {
            "taken_by": "your_name",
            "taken_because": "backup before upgrading OKA"
      }
}'
Note

The default behavior for selecting indices in a snapshot operation is to include all indices ("indices": "*"). To specify a selection of specific indices, the “indices” field should be modified to list the desired index names, separated by commas ("indices": "index1,index2,index3").

On completion, check in the output the "state" of the backup, it should be "SUCCESS".

Note

Snapshots must be identified by unique names. The above command use the date of the snapshot as unique identifier (snapshot_oka_$(date +%Y%m%d)).

Note

You can add multiple metadata to your snapshot. We recommend to add at least your name and the reason why the snapshot was taken.

Note

Over time, snapshot repositories can accumulate stale data that is no longer referenced by existing snapshots. Use this command to clean the snapshot repository curl -XPOST "host:port/_snapshot/my_backup/_cleanup". In case you need to copy the snapshot to another Elasticsearch (e.g., preproduction VM), we recommend that you run this command first. This command can take a long time to complete.

Restore

Important

If restoring to a new version of elasticsearch, the 4 steps in configure your snapshot directory should be repeated for this new version.
curl -X POST "http://host:port/_snapshot/my_backup/snapshot_oka_20240123/_restore" -H 'Content-Type: application/json'
Note

Modify the snapshot name (<SNAPSHOT NAME>) to match the one provided during the backup procedure. You can list the available snapshots with:
curl -X GET "http://host:port/_cat/snapshots/my_backup"
Note

You can make this command synchronous by adding ?wait_for_completion=true after _restore.

PostgreSQL

Backup

First, ensure that PostgreSQL database ise running and accessible.
Backup your PostgreSQL database:
pg_dump --dbname=oka_db --host=HOSTNAME --port=PORT --username=oka --password > oka_db.backup.sql

Restore

sudo -i -u postgres
psql
      DROP DATABASE oka_db;
      CREATE DATABASE oka_db;
      GRANT ALL PRIVILEGES ON DATABASE oka_db TO oka;
      ctrl+d
psql oka_db < oka_db.backup.sql
ctrl+d
sudo service postgresql restart

In case something went wrong during the update, you can go back to the previous OKA version. You must first uninstall OKA (see Uninstalling OKA).

Once the databases have been saved, you can proceed and install the new version using OKA installer (see Deployment).

Once the databases are restored, you can proceed with the following steps:

Save your oka.conf file: cp "${OKA_INSTALL_DIR}/conf/oka.conf" /tmp/oka.conf

Delete current_version file: rm ${OKA_INSTALL_DIR}/current-version

Install the previous version using the desired OKA installer (see Deployment).

Check if the new oka.conf file matches with the one previously saved, or report any specific customization.

Restart OKA services: sudo systemctl start oka.service