This guide walks you through the process of upgrading your Package Security Manager installation to a newer version. Package Security Manager supports in-place upgrades, meaning you can upgrade while the software is running.

1

Verify system requirements

Ensure your environment meets the new version’s system requirements.

If upgrading your OS to RHEL 9, you must first switch from Docker to Podman.

2

Create backups

Create backups of the following files:

  • docker-compose.yml
  • .env

These contain your custom configurations and will be overwritten during the upgrade!

  1. Open a terminal.

  2. Log in to your Package Security Manager server.

  3. Navigate to your Anaconda installer directory (ate-installer-*) by running the following command:

    # Replace <INSTALLER_DIR> with your installer directory
    cd <INSTALLER_DIR>
    

    Start typing ate-installer- in your terminal, then press Tab to autocomplete the directory name.

  4. Create a backup of the docker-compose.yml file by running the following command:

    cp docker-compose.yml ../docker-compose.yml.backup
    
3

Verify service account permissions

If you are using Package Security Manager 6.1.6 or later, you can skip this step.

You must verify the correct permissions are set for the service account to prevent users from losing their assigned permissions:

  1. Log in to your Keycloak admin panel at https://<YOUR_DOMAIN>/auth/admin.
  2. Navigate to Clients and select repo-account-sync.
  3. Select the Service Account Roles tab.
  4. Open the Client Roles dropdown and select realm-management.
  5. Add manage-users and manage-realm to the Assigned Roles.
4

Download the installer

Download the installer using the URL provided by Anaconda:

# Replace `<INSTALLER_LOCATION>` with the provided installer URL
curl -O <INSTALLER_LOCATION>
5

Run the upgrade

Choose the appropriate command based on your setup:

# Replace `<INSTALLER>` with the installer you just downloaded
# Replace `<PATH_TO_REPO_FOLDER>` with the path to your repository - the default path is /opt/anaconda/repo
# Replace `<FQDN>` with your fully qualified domain name
# Replace `<PREVIOUS_INSTALLER>` with the location of the previous installer file (where the docker-compose.yml is located)
bash `<INSTALLER>`  -- -b `<PATH_TO_REPO_FOLDER>` -d `<FQDN>` --upgrade-from ../`<PREVIOUS_INSTALLER>`

If your current version of Package Security Manager is utilizing Grafana, you must include the following argument in your upgrade. If you do not, you will lose access to your Grafana dashboards. Upgrading removes your previous version of Grafana.

--grafana-monitor-stack

Don’t forget to log in and update your password for your Grafana monitoring dashboards!

Once the upgrade is complete, run the following command to instruct Keycloak to allow HTTP traffic:

# Replace `<ADMIN_PASSWORD>` with the password used to log in to Keycloak as user "admin"
docker compose exec -T keycloak ./bin/kcadm.sh update realms/master -s sslRequired=NONE --server http://localhost:8080/auth --realm master --user admin --password `<ADMIN_PASSWORD>`

If your upgrade fails at this point, it is likely due to a permissions issue with your Redis cache. To complete the upgrade, reset permissions for your Redis cache and restart your containers by running the following commands:

docker compose down
chmod 644 "<BASE_INSTALL_DIR>/state/redis/data/dump.rdb"
docker compose up --detach
6

Restore configurations

If necessary, restore your custom configurations from the backup files you created when you began the upgrade process.

Additional considerations:

  • For upgrades to Package Security Manager 6.6.2 or later, see Upgrading Postgres.
  • To support artifacts larger than 3GB, see Increasing artifact upload size limit.
  • If using a custom implementation, verify that your docker-compose.yml and repo.conf (nginx configuration) files reflect the upgraded changes.