> ## 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.4.0/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>
        ```

        <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>
        ```

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