Upgrade Supermarket

Upgrade Matrix

If running Supermarket 4.2, you can upgrade directly to the latest releases of Supermarket 5.0. If you are running a release with version less than 4.2 you must perform a stepped upgrade as outlined below.

Supported Release

Chef Supermarket uses the PostgreSQL database. PostgreSQL 9.3 is EOL and Private Supermarket users should upgrade to Supermarket 5.0 or above and migrate to PostgreSQL 13.

Chef Software supports Supermarket 5.0 release and later. Earlier releases are not supported. For more information about supported Chef Software see the Supported Versions documentation.

Upgrade a Private Supermarket

Every Private Supermarket installation is unique. These are general steps for upgrading a Private Supermarket.

1. Stop the Supermarket services:

   sudo supermarket-ctl stop
   

2. Backup the /var/opt/supermarket directory.

3. Download the Chef Supermarket package from Chef Downloads.

4. Upgrade your system by installing the new package using the appropriate package manager for your distribution:

   • For Ubuntu:

     dpkg -i /path/to/package/supermarket*.deb
     

   • For RHEL / CentOS:

     rpm -Uvh /path/to/package/supermarket*.rpm
     

5. Reconfigure Chef Supermarket server:

   sudo supermarket-ctl reconfigure
   

6. Once the Private Supermarket upgrade finishes, restart the services that run Chef Supermarket to clear the old installation of Chef Supermarket from the server memory.

   systemctl list-units | grep runsvdir
   

7. Restart the unit:

   systemctl restart UNIT_NAME
   

   This will restart the runsvdir, runsv, and svlogd service processes that run Chef Supermarket.

Release Specific Upgrade: Supermarket 5.0 and PostgreSQL 13.4

Supermarket 5.0 upgrades PostgreSQL from 9.3 to 13.4. The 5.0 upgrade process requires a one-time downtime to vacuum, upgrade, and re-index the database.

Supermarket 5.0 Changes

Prepare for the upgrade by following these steps:

1. Set the attribute: default['supermarket']['postgresql']['pg_upgrade_timeout'] in supermarket.rb to the intended timeout value (in seconds) for the upgrade. Set this value based on the size of your data.
2. PostgreSQL 13 deprecated the checkpoint-segments attribute and we have removed it from the Supermarket configuration. Remove this entry from your configuration:

default['supermarket']['postgresql']['checkpoint_segments']

PostgreSQL 13.4 Upgrade

Each Private Supermarket installation is unique. The PostgreSQL upgrade steps are a general process intended for the internal PostgreSQL.

• External PostgreSQL: The end user is responsible for upgrading and maintaining External PostgreSQL configurations.
• Internal PostgreSQL: The PostgreSQL upgrade steps are a general process intended for the internal PostgreSQL.

1. Backup the Supermarket database:

   Database migrations have inherent risk to your system. Create a backup before beginning any migration or update. This ensures that you have a recoverable state in case any step in the process fails. Copy the backup to a another disk that is not connected to the Private Supermarket installation. This ensures that you have state to restore, in case of a failure in the upgrade process

   Back up the PostgreSQL database before upgrading so you can restore the full database to a previous release in the event of a failure in the upgrade steps below.

   sudo -u supermarket /opt/supermarket/embedded/bin/pg_dumpall -U supermarket 1543 > /  tmp/supermarket-dump.sql
   

2. Vacuum the database:

   Run VACUUM FULL on the PostgreSQL database if you don’t have automatic vacuuming set up. This process will reduce the size of the database by deleting unnecessary data and speeds up the migration. The VACUUM FULL operation takes around 1 to 2 minutes per gigabyte of data depending on the complexity of the data, and requires free disk space at least as large as the size of your database.

   For more information on upgrading using vacuumdb see the PostgreSQL 13 documentation for vacuumdb.

   sudo -u supermarket /opt/supermarket/embedded/bin/vacuumdb --all --full -p 15432
   

3. Upgrade Supermarket:

   Follow the Upgrade a Private Supermarket steps.
   
   

4. Cleanup the installation:

   Follow these steps to clean up the old PostgreSQL installation and other clutter in the cache.

   1. Stop the Supermarket application:

      sudo supermarket-ctl stop
      

   2. Start the newly installed PostgreSQL server.

      sudo supermarket-ctl start postgresql
      

5. Reindex the database:

   reindexdb is a utility for rebuilding indexes in a PostgreSQL database.

   For more information on upgrading using reindexdb see the PostgreSQL 13 documentation for reindexdb.

   sudo -u supermarket /opt/supermarket/embedded/bin/reindexdb --all -p 15432
   

6. Restart Supermarket:

   sudo supermarket-ctl restart
   

Troubleshooting

Recovering from Database Cleanup Failures

If either the vacuumdb or reindexdb commands fail

1. Drop the Supermarket PostgreSQL database

   /opt/supermarket/embedded/bin/psql -U supermarket -d postgres -p 15432 -c "drop database supermarket"
   

2. Recreate the Supermarket PostgreSQL database

   /opt/supermarket/embedded/bin/psql -U supermarket -d postgres -p 15432 -c "create database supermarket"
   

3. Restore Supermarket PostgreSQL database from the existing dump file: supermarket-dump-archive.sql

   /opt/supermarket/embedded/bin/psql -U supermarket -d supermarket -p 15432 -f /tmp/supermarket-dump-archive.sql
   

4. Restart the Supermarket application

   supermarket-ctl restart