> ## Documentation Index
> Fetch the complete documentation index at: https://anaconda.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading Anaconda Server

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

## Upgrade process

<Steps>
  <Step title="Verify system requirements">
    Ensure your environment meets the new version's [system requirements](/docs/psm-on-prem/6.5.3/prep/main).

    <Warning>
      If upgrading your OS to RHEL 9, you must first [switch from Docker to Podman](./docker_to_podman).
    </Warning>
  </Step>

  <Step title="Create backups">
    Create backups of the `docker-compose.yml` and `.env` files:

    <Note>
      These contain your custom configurations and will be overwritten during the upgrade!
    </Note>

    1. Open a terminal.

    2. Log in to the server that hosts your Anaconda Server installation.

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

       ```sh theme={null}
       # Replace <INSTALLER_DIR> with your installer directory
       cd <INSTALLER_DIR>
       ```

           <Tip>
             Type "ate-installer-", then press Tab to autocomplete the directory name.
           </Tip>

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

       ```sh theme={null}
       sudo cp docker-compose.yml ../docker-compose.yml.backup
       sudo cp .env ../.env.backup
       ```
  </Step>

  <Step title="Verify service account permissions">
    <Note>
      If you are using Anaconda Server 6.1.6 or later, you can skip this step.
    </Note>

    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**.
  </Step>

  <Step title="Download the installer">
    Download the installer using the URL provided by Anaconda:

    ```sh theme={null}
    # Replace `<INSTALLER_LOCATION>` with the provided installer URL
    curl -O <INSTALLER_LOCATION>
    ```
  </Step>

  <Step title="Run the upgrade">
    Choose the appropriate command based on your setup:

    <Tabs>
      <Tab title="HTTPS">
        If your setup uses HTTPS protocol, you'll need to provide the TLS certificate and key in your installation command:

        ```sh theme={null}
        # 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>
        ```

        <Warning>
          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.

          ```sh theme={null}
          --grafana-monitor-stack
          ```

          Don't forget to log in and update your password for your [Grafana monitoring dashboards](/docs/psm-on-prem/6.8.0/admin/integrations/grafana)!
        </Warning>

        <Note>
          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:

          ```sh theme={null}
          docker rm $(docker ps -aqf status=exited)
          ```
        </Note>
      </Tab>

      <Tab title="HTTP">
        ```sh theme={null}
        # 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>
        ```

        <Warning>
          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.

          ```sh theme={null}
          --grafana-monitor-stack
          ```

          Don't forget to log in and update your password for your [Grafana monitoring dashboards](/docs/psm-on-prem/6.8.0/admin/integrations/grafana)!
        </Warning>

        <Note>
          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:

          ```sh theme={null}
          docker rm $(docker ps -aqf status=exited)
          ```
        </Note>

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

        ```sh theme={null}
        # 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>`
        ```
      </Tab>
    </Tabs>

    <Warning>
      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:

      ```sh theme={null}
      docker compose down
      chmod 644 "<BASE_INSTALL_DIR>/state/redis/data/dump.rdb"
      docker compose up --detach
      ```
    </Warning>
  </Step>

  <Step title="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.
  </Step>
</Steps>