```{title} Single Server Upgrade
```

# Single Server Upgrade

## Automated Upgrade

The automated upgrade script can be used to upgrade a previous installation to {{ release }} .

Administrators have several options to choose from with out to handle replacing existing images.

```{eval-rst}
.. parsed-literal::

   Flag                       Description
   ------------------------------------------------------------------------------------
   | -h|--help                | Display this help menu                                |
   | -L|--proxy-port          | Default Proxy Listening Port                          |
   | -I|--no-images           | Don't seed or pull default Workspaces Images          |
   | -U|--upgrade-images      | Upgrade Images to current set purging previous images |
   | -K|--add-images          | Ingest the latest images keeping old images in place  |
   | -w|--offline-workspaces  | Path to the tar.gz workspace images offline installer |
   | -s|--offline-service     | Path to the tar.gz service images offline installer   |
   | -S|--role                | Role to Upgrade: [app | db | agent]                   |
   ------------------------------------------------------------------------------------

```

In this example {code}`--upgrade-images` and {code}`--proxy-port` is used.

```{parsed-literal}
cd /tmp
curl -O {{ release_url }}
tar -xf kasm_release*.tar.gz
sudo bash kasm_release/upgrade.sh --upgrade-images --proxy-port 4443
```

## Manual Upgrade

Kasm Tech recommends installing a separate instance of the application, migrating the data and performing a cutover of the application.

Please read through the entire process before getting started.

```{include} /install/offline_install_note.md
```

```{include} image_warning.md
```

**Create a Database Backup**

Backup the existing Kasm database. This can be saved for later recovery, but will also be used to migrate existing data to the latest version.

- Stop existing Kasm Services

```Bash
sudo /opt/kasm/bin/stop
```

- Execute the database backup utility

```{parsed-literal}
sudo mkdir -p /opt/kasm/backups/
sudo bash /opt/kasm/{{ previous_release }}/bin/utils/db_backup -f /opt/kasm/backups/kasm_db_backup.tar -p /opt/kasm/{{ previous_release }}/
```

- Verify the presence and location of the database backup

```Bash
sudo ls -al /opt/kasm/backups/kasm_db_backup.tar
```

```{note}
If you are performing an offline upgrade please ensure that you have downloaded and installed versions of docker and docker compose that meet the updated system requirements see {doc}`System Requirements <../install/system_requirements>` for details.
```

- Download and extract the new installation media

```{parsed-literal}
cd /tmp
curl -O {{ release_url }}
tar -xf kasm_release_*.tar.gz
```

- Get the existing database password for use in the subsequent commands.

```{parsed-literal}
sudo grep " password" /opt/kasm/{{ previous_release }}/conf/app/api.app.config.yaml
```

- Get the existing manager token for use in the subsequent commands.

```{parsed-literal}
sudo grep "token" /opt/kasm/{{ previous_release }}/conf/app/agent.app.config.yaml
```

______________________________________________________________________

**Perform a clean install**

- Install kasm from the release media downloaded in the prior steps.

  - When performing an offline update add these flags `-w <KASM_WORKSPACE_IMAGES_TAR> -s <KASM_SERVICE_IMAGES_TAR>`

```Bash
sudo bash kasm_release/install.sh -D -Q <DATABASE_PASSWORD> -M <MANAGER_TOKEN>
```

**Modify Configs**

- Copy the **server_id** and the **public_hostname** properties from the old agent to the new

```{parsed-literal}
grep server_id /opt/kasm/{{ previous_release }}/conf/app/agent.app.config.yaml
grep public_hostname /opt/kasm/{{ previous_release }}/conf/app/agent.app.config.yaml
sudo vi /opt/kasm/{{ release }}/conf/app/agent.app.config.yaml
```

- Copy **manager_id** and **server_hostname** from the old configuration into the new

```{parsed-literal}
grep manager_id /opt/kasm/{{ previous_release }}/conf/app/api.app.config.yaml
grep server_hostname /opt/kasm/{{ previous_release }}/conf/app/api.app.config.yaml
sudo vi /opt/kasm/{{ release }}/conf/app/api.app.config.yaml
```

- Copy the auto-generated nginx configs for any sessions that may exist on the Agent

```{parsed-literal}
sudo cp /opt/kasm/{{ previous_release }}/conf/nginx/containers.d/* /opt/kasm/{{ release }}/conf/nginx/containers.d/
```

______________________________________________________________________

**Restoring the Database.**

Restore and update the database from the prior version

- Ensure all Kasm services are stopped

```Bash
sudo /opt/kasm/bin/stop
```

- Execute the database restore command

```{parsed-literal}
sudo /opt/kasm/{{ release }}/bin/utils/db_restore -f /opt/kasm/backups/kasm_db_backup.tar -p  /opt/kasm/{{ release }}
```

- Perform an upgrade of the database schema

```{parsed-literal}
sudo /opt/kasm/{{ release }}/bin/utils/db_upgrade -p /opt/kasm/{{ release }}
```

- Install The Kasm {{ release }} Default Images for your platform

  - If doing an offline upgrade first extract the default image seed data from the workspace images tar

    For x86 (amd64) platforms:

    ```{parsed-literal}
    tar xf <KASM_WORKSPACE_IMAGES_TAR> --strip-components=1 -C /opt/kasm/{{ release }}/conf/database/seed_data/ workspace_images/default_images_amd64.yaml
    ```

    For ARM (arm64) platforms:

    ```{parsed-literal}
    tar xf <KASM_WORKSPACE_IMAGES_TAR> --strip-components=1 -C /opt/kasm/{{ release }}/conf/database/seed_data/ workspace_images/default_images_arm64.yaml
    ```

For x86 (amd64) platforms:

```{parsed-literal}
sudo /opt/kasm/{{ release }}/bin/utils/db_init -s /opt/kasm/{{ release }}/conf/database/seed_data/default_images_amd64.yaml
```

For ARM (arm64) platforms:

```{parsed-literal}
sudo /opt/kasm/{{ release }}/bin/utils/db_init -s /opt/kasm/{{ release }}/conf/database/seed_data/default_images_arm64.yaml
```

- Start the Kasm services

```Bash
sudo /opt/kasm/bin/start
```

```{include} upgrade_images.md
:start-line: 2
```