Upgrading Package Security Manager

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.

Upgrade process

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.

Create backups

Create backups of the docker-compose.yml and .env files:

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

Open a terminal.
Log in to the server that hosts your Package Security Manager installation.
Navigate to your Anaconda installer directory (ate-installer-*) by running the following command:
# Replace <INSTALLER_DIR> with your installer directory cd <INSTALLER_DIR>
Type “ate-installer-”, then press Tab to autocomplete the directory name.

Create backups of your configuration files by running the following commands:

sudo cp docker-compose.yml ../docker-compose.yml.backup
sudo cp .env ../.env.backup

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:

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

Download the installer

Download the installer using the URL provided by Anaconda:

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

Run the upgrade

Choose the appropriate command based on your setup:

HTTPS
HTTP

If your setup uses HTTPS protocol, you’ll need to provide the TLS certificate and key in your installation command:

# 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 <PATH_TO_CERT> and <PATH_TO_KEY> with your TLS certificate and key paths
# Replace <PREVIOUS_ATE_INSTALLER_DIR> with the location of the previous installation (where the docker-compose.yml is located)
sudo bash <INSTALLER> -- -b <PATH_TO_REPO_FOLDER> --domain <FQDN> --tls-cert <PATH_TO_CERT> --tls-key <PATH_TO_KEY> --upgrade-from ../<PREVIOUS_ATE_INSTALLER_DIR>

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!

If you’re upgrading with Podman and you encounter an error similar to the following:

Error response from daemon: container create: creating container storage: the container name "nginx-exporter" is already in use by...<CONTAINER_ID>. You have to remove that container to be able to reuse that name: that name is already in use

You can safely remove the existing containers and create new ones by running the following command from inside your ate-installer-* directory:

docker rm $(docker ps -aqf status=exited)

# 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_ATE_INSTALLER_DIR> with the location of the previous installer file (where the docker-compose.yml is located)
sudo bash <INSTALLER>  -- -b <PATH_TO_REPO_FOLDER> -d <FQDN> --upgrade-from ../<PREVIOUS_ATE_INSTALLER_DIR>

--grafana-monitor-stack

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

If you’re upgrading with Podman and you encounter an error similar to the following:

Error response from daemon: container create: creating container storage: the container name "nginx-exporter" is already in use by...<CONTAINER_ID>. You have to remove that container to be able to reuse that name: that name is already in use

You can safely remove the existing containers and create new ones by running the following command from inside your ate-installer-* directory:

docker rm $(docker ps -aqf status=exited)

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

Reapply configurations

If necessary, review the docker-compose.yml.backup and .env.backup files you created when you began the upgrade process, reapply your custom configurations to your new installations configuration files, and verify that your repo.conf (nginx configuration) file also reflects the upgraded changes.

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.

​Upgrade process

​Additional considerations

Upgrade process

Additional considerations