Migration guide from Stretch to Buster

This guide will help you upgrade your REVEN installation, whether based on a regular archive or a Docker image, from any version running on Debian Stretch (<=2.7.1) to any version running on Debian Buster (>=2.8.0). For the sake of simplicity, it will assume and present commands for a 2.7.1 to 2.8.0 migration.

A manual operation is needed in the process because of the transition from PostgreSQL 9.6 to PostgreSQL 11.

There will be three main steps: dumping your database, upgrading your system to Buster, then restoring the database.

For non-Docker users

This section is for users that use the regular REVEN archive, not the Docker image. If you use the Docker image, chances are that you even don't run Debian Stretch in the first place, so please read the next section.

Preparing the files

Please be sure that you have the dump.sh and restore.sh scripts accessible from the user running REVEN. These scripts are available both from the REVEN package you downloaded (in the tools/debian_upgrade folder of the standard package, or directly in the debian_upgrade folder in the Docker package), or from Github.

Dumping the database

In the procedure below, we assume that the QUASAR_ROOT folder is the default ~/Reven2. Should you have customized the QUASAR_ROOT setting, please adapt the procedure accordingly.

IMPORTANT: These steps are to be performed before the migration while you are still running Debian Stretch and REVEN 2.7.1:

  1. Open a shell with the user that runs REVEN.
  2. Go to your 2.7.1 REVEN installation folder (the one where you extracted your 2.7.1 REVEN package to).
  3. Run ./start.sh to start everything.
  4. Run ./dump.sh. Check that a dump-2.7.1.sql file was created in your ~/Reven2 folder.
  5. Run ./stop.sh to stop everything.
  6. (Optional but recommended) Also make an external backup of your ~/Reven2 folder, so that even if something goes wrong, you will be able to restore your data.

You can repeat those steps any time you want if you thought of some last-minute changes to your REVEN data. Just be sure to have a dump of the latest state of the database before the OS upgrade.

Upgrading your system to Buster

A comprehensive guide is provided by Debian https://wiki.debian.org/DebianUpgrade and is the most up to date and trustworthy place to find documentation on Debian upgrades.

IMPORTANT: The kvm group of your Stretch installation may cause issues during the upgrade process. To avoid them, please delete the group before upgrading. The group will be recreated later automatically: sudo groupdel kvm.
If you forgot this step and encounter the following error during upgrade: The group 'kvm' already exists and is not a system group. Exiting. simply delete the kvm group at that moment, and run sudo apt install -f to let apt configure the failed packages, then continue the upgrade procedure as usual.

Restoring the database

These steps are performed after the migration while you are now running Debian Buster and REVEN 2.8.0.

In the procedure below, we assume that the QUASAR_ROOT folder is the default ~/Reven2. Should you have customized the QUASAR_ROOT setting, please adapt the procedure accordingly.

  1. Open a shell with the user that runs REVEN.
  2. Go to your REVEN installation folder.
  3. Run ./install.sh to ensure all the system dependencies are installed.
  4. Run ./start.sh a first time.
  5. If you need to restore parameters into the settings.py configuration file, now is the right time to do it.
  6. Now we need to get the right data at the right place, including the database to migrate. The easiest way to do that is to attempt to start REVEN, which will end with an expected failure since the database was not restored yet.
    Run ./start.sh a second time.
    Use the script interface to migrate your old data to the new REVEN version.
  7. The previous step should leave you with an error message that looks like the following: 
    A process (postgres) failed to start (cmd: '/usr/lib/postgresql/11/bin/postgres -D /home/<user>/Reven2/2.8.0/db-2.8.0.psql -k /tmp/tetrane-1000 -p 37221')
    The part you are interested in is after the -D argument. This is the path to your PostgreSQL database that needs migration.
  8. Run the following, of course adapting the <user> part to your situation: ./restore.sh /home/<user>/Reven2/2.8.0/db-2.8.0.psql /home/<user>/Reven2/dump-2.7.1.sql
  9. Finally, run ./start.sh one last time. As you have already handled the migration in step (6), you need to keep using your existing data, so answer no when the script asks if it should overwrite the data directory.

The REVEN Project Manager is now up and running. Enjoy!

If you made any mistake during one of these steps, don't panic. You can repeat them over and over, until you have restored the right database in your REVEN Project Manager.

For Docker users

This section is for users that use the REVEN Docker image. If you don't run REVEN through Docker, please read the previous section.

Preparing the files

Please be sure that you have the dump.sh and restore.sh migration scripts accessible from the user running REVEN. These scripts are available in the debian_upgrade folder in the Docker package, or from Github.

As the user running REVEN is inside the running container, the best place for you to put the dump.sh and restore.sh migration scripts is probably your REVEN2_PATH that defaults to ~/Reven2 on your host.

Inside the container, the REVEN2_PATH will be accessible in the /Reven2 directory and the REVEN installation folder in /reven.

Dumping the database

These steps are performed using the Stretch-based REVEN container (<=2.7.1).

  1. Ensure your REVEN container is running: ./run.sh.
  2. Get a shell inside the running container: docker exec -it <username>-reven su reven
  3. Make the dump: /Reven2/dump.sh
  4. Exit the container: exit
  5. Stop the container: ./run.sh

You should now have a dump-2.7.1.sql file in your ~/Reven2 directory.

You can repeat those steps any time you want if you thought of some last-minute changes to your REVEN data. Just be sure to have a dump of the latest state of the database before the REVEN upgrade.

Upgrading your REVEN version

Just as usual, download a REVEN 2.8.0 Docker package and extract it in the directory of your choice, for example using tar xvf <package>.

Restoring the database

These steps are performed after the extraction of the REVEN 2.8.0 Docker package.

In the procedure below, we assume that the REVEN2_PATH folder defined in the run.sh script is the default ~/Reven2. Should you have customized the REVEN2_PATH setting, please adapt the procedure accordingly.

  1. We first need to get the right data at the right place, including the database to migrate. The easiest way to do that is to attempt to start the REVEN container.
    This will end with an expected failure since the database was not restored yet.
    Run ./run.sh a first time.
    Use the script interface to migrate your old data to the new REVEN version.
  2. The previous step should leave you with an error message that looks like the following: 
    A process (postgres) failed to start (cmd: '/usr/lib/postgresql/11/bin/postgres -D /Reven2/2.8.0/db-2.8.0.psql -k /tmp/tetrane-1000 -p 37221')
    The part you are interested in is after the -D argument. This is the path to your PostgreSQL database that needs migration.
  3. Stop the container: ./run.sh.
  4. Run a temporary container to perform the migration:
    docker run -it --rm --entrypoint bash -v ~/Reven2:/Reven2 tetrane/reven2:2.8.0-enterprise -c 'su reven'
    Of course, adapt the Docker image name (tetrane/reven2:2.8.0-enterprise) to the one you are using.
    1. Run the restore process: /Reven2/restore.sh /Reven2/2.8.0/db-2.8.0.psql /Reven2/dump-2.7.1.sql
    2. You can now close the temporary container: exit.
  5. Run a final ./run.sh.

The REVEN Project Manager is now up and running. Enjoy!

If you made any mistake during one of these steps, don't panic. You can repeat them over and over, until you have restored the right database in your REVEN Project Manager.

©2019-2021 Tetrane