6. Maintain Agora

6.1. Update Agora

it is recommended to maintain your Agora installation up-to-date. Updating Agora to the newest version is a simple process. To prepare for a version update, performing a full database backup upfront is recommended. This is described in the next paragraph. Also plan the update to take place in a period with no user activity, as the process requires 2-5 minutes of downtime.

To update Agora without backup, type gtagora update.

gtagora will suggest to update to the latest version for which a license is available. After accepting, the tool will download the new container images and restart Agora.

Important

Always use the latest version of the gtagora tool. The command gtagora update will check for a new version of the gtagora tool. If a new version exists, update the tool with gtagora update-installer.

6.2. Update with the possibility to return to the previous version

1. Open Agora in the Browser and take note of the current version

2. Shutdown Agora

gtagora stop

2. Backup the config.json and the coressponding docker-compose.yml file

cp /etc/gyrotools/agora/config.json /backup/
cp /etc/gyrotools/agora/docker-compose.yml /backup/

3. Create a backup directory. Make a copy of the docker volumes agora_db and agora_mongo.

rsync -aP /path/to/agora_db /backup/
rsync -aP /path/to/agora_mongo /backup/

Important

It is important to shut down Agora before copying the database folders. Copies of database folders created during operation are not reliable backups!

Tip

To find out which directory a Docker volume points to, the docker volume inspect VOLUME_NAME command can be used.

3. Update Agora

gtagora update

4. The update command will restart Agora. Check if Agora works properly.

If it becomes necessary to restore Agora to the old version (eg because of a failed update), proceed as follows:

1. Shutdown Agora

gtagora stop

2. Restore the database backups

rm -rf /path/to/agora_db/*
rm -rf /path/to/agora_mongo/*

rsync -aP /backup/agora_db/ /path/to/agora_db/
rsync -aP /backup/agora_mongo/ /path/to/agora_mongo/

3. Restore the configuration

cp /backup/config.json /etc/gyrotools/agora/
cp /backup/docker-compose.yml /etc/gyrotools/agora/

4. Apply the changes

gtagora rebuild

5. Start Agora

gtagora start

6.3. Update to a specific version

gtagora update <VERSION> updates agora to the specified version.

Important

Downgrades are generally not possible. The result could be a serious loss of data.

6.4. Update Agora-Installer

When the wizard (gtagora without arguments) is started, it automatically checks if a new version of the Agora installer is available. The Agora installer can also be updated with the gtagora update-installer command.

To update the Agora Installer manually, download it from from http://download.gyrotools.com/download/getagora/gtagora and save the binary in /usr/bin/. Before you can run the binary, set the appropriate persmission (chmod +x /usr/bin/gtagora)

6.5. Move data

It may be necessary to move an Agora storage location to another disk. This may be to replace an old disk or to store the data on a larger or faster disk.

Important

Special care should always be taken when copying or moving data, as errors can happen all too quickly. Make sure that you have a backup of the data in any case.

Before you start moving or copying data, stop the Agora. Otherwise it can lead to serious data loss or even worse to a corrupt database. Agora uses docker volumes to store data. With the following command all volumes can be displayed. The volumes are created by the installer. The most important volumes in Agora are:

• agora_data_1: contains the data files

• agora_db: contains the database files

The following is an example of how to move Agora database data. It works exactly the same with all other data volumes.

Stopping Agora

gtagora stop

Check if all agora container are down

docker ps

docker ps
CONTAINER ID  IMAGE  COMMAND  CREATED  STATUS  PORTS  NAMES

Now inspect the volume that you want to move (one of agora_db, agora_data_1, agora_log, agora_nginx)

docker volume inspect <VOLUME_NAME>

[
    {
        "CreatedAt": "2020-05-19T23:25:29+02:00",
        "Driver": "local",
        "Labels": {},
        "Mountpoint": "/var/lib/docker/volumes/agora_db/_data",
        "Name": "agora_db",
        "Options": {
            "device": "/data/test4/volumes/db",
            "o": "bind",
            "type": "none"
        },
        "Scope": "local"
    }
]

The “device” value should reflect the current data location of this volume. Copy or move the data to a new location.

rsync -aP /data/test4/volumes/db /data_new/test4/volumes/db

Now we recreate the volume with the new location:

docker volume rm agora_db
docker volume create agora_db --opt type=none --opt device=/data_new/test4/volumes/db --opt o=bind

Important

It can happen that Docker stops with the error message “Volume in use” when deleting volumes. To solve this problem you should first check if there are really no relevant containers running.

docker ps

Then you can show all containers that have a reference to a certain volume. For VOLUME_NAME use the name of the volume you want to move.

docker ps -a --filter volume=VOLUME_NAME

The list should only show you containers with status=exited

Now delete all the exited containers:

docker rm $(docker ps -q --filter status=exited --filter volume=VOLUME_NAME)

Try again to delete the desired volume.

Start Agora

gtagora start