Updating from a past version

Updating your system

Here you will learn on how to update your Snap4City distribution from one version to another one. Note that you may only update a MicroX generated with this tool; we cannot guarantee for any other scenario.

Step 1 - Download the tools

Click here to download the scripts which will aid you in updating your distribution.

Step 2 - Backup everything

It never hurts to do so, use the backing-up-volumes/backup.sh script to backup your docker volumes. You might want to make a separate dump of the database.

Step 3 - Use your token to regenerate your distribution

You will still need to provide values for variables which didn't exist at the time you first generated your distribution, be sure to check the values which have default values.

Step 4 - Unzip the updated new configuration on the host

Be sure that the directory which contains the configuration files shares the name with the old one; this should be true by default.

Step 5 - Stop the execution of the containers

Use docker-compose down to drop the containers; run this command in the old drectory. You might alternatively, if you have access to the docker GUI, stop them from the mentioned GUI.

Step 6 - Run the script which imports the old data from local volumes

Nifi, IoTapps and OpenSearch require data from your current installation; running fix-files/adjust_for_updates.sh will import said data. Before running the script, you must edit the paths (source and destination).

Step 7 - Copy paste the old folder into the new one, without pasting files which already exist

This will fix the rest of the configuration files.

Step 8 - Start the old database container

We need some of the old data.

Step 9 - Update the database schema

The script updating/update_db.py detects the current version of the db and trasforms its schema in order to be up to date in regard to the S4C version to which you are updating. You'll need to open the script and set your database credentials.

Step 10 - Dump the tables which need to be preserved

The script updating/dump_db.py does this automatically. You'll need to open the script and set your database credentials.

Step 11 - Stop the old database container, delete its volume, then run the new database container

Do not skip the second operation, or else the new container will try to use the old volume. Due to step 2, you will be able to restore your data if the need arises.

Step 12 - Import the dump from step 10

Either use the script updating/load_db.py or use tools like MySQL Workbench. You'll need to open the script and set your database credentials.

Step 13 - Start the containers with docker-compose up -d

The database is already running and requires no further operations.

Step 14 - Run the post-setup.sh script in the new distribution

This will fix some details in the kb.

Step 15 - Log in all of your IoT-Apps

This is required to regenerate the refresh token for authentication purposes

Restoring volumes in case of downgrade to the original version

If you want to return to the original version, you should try the following the instructions which explain different scenarios. Note that multiple might apply, depending on your situation.

Case 1 - No volume was lost or edited, no files were deleted

This happens if you proceeded to the upgrade without following the steps 9-12 from above. You don't need to do anything as all the data is where you left it.

Case 2 - No volume except for the database was lost or edited, no configuration files were deleted

All you need to do is to drop the volume of the database then restore the dump taken during step 2. Should you not have said dump but have the volume saved to a file from step 2, refer to Restore a volume.

Case 3 - Any number of volumes were lost, but said volumes saved to files are avaiable

Refer to Restore a volume to restore a container. You might need to iterate the process for multiple containers.

Case 4 - Some files were lost, volumes backup are not available

Some of the files might need simply regenerated by using your token to regenerate a configuration. Files which are generated during setup will need to be regenerated if missing, resulting possibly in inconsistencies due to keys generation; you might need to call for specific support. Files which are generated locally on your host cannot be restored short of restoring a periodic backup or restoring a deleted file. The latter is a process which can lead to an irrecuperable losses.

Restore a volume

Restore a volume from a file

If you have a volume saved to a file genereated from step 2, you will need to run backing-up-volumes/restore.sh to recreate it (All volumes in the path where the script is executed are restored). The volume will have the name of the file. Be sure not to restore a volume on a preexisting volume to avoid inconsinstencies (but you can run the same script multiple times if nothing else edits the volumes).

Use an existing volume in a container which didn't generate it

If you need to use an existing volume in a container, for example because it is already populated by data (assuming there are no issues reading such a volume), you will need to edit the docker-compose.yaml file.

Go at the bottom of the file, on the section volumes
For each volume which you need to have already existing, add a value external set to true
On the same level and volume, add a value name set to the name of your container

Here is an example:

volumes:
  dashboarddb:
#####
volumes:
  dashboarddb:
    external: true
    name: some_name

Note that telling docker that the container is external will skip the creation of the volume, meaning that a container won't start unless the volume already exists.