---
myst:
  html_meta:
    "description lang=en": "Manual and automated upgrade process documentation for Kasm Workspaces single server deployments."
    "keywords": "Kasm, Workspace, Single-server, Single, Server, Upgrade"
    "property=og:locale": "en_US"
---
```{title} Single Server Upgrade
```

# Single Server Upgrade

```{warning}
When running any upgrade please ensure there are no active Kasm Workspaces sessions running. On large deployments this will likely require a maintenance window.
```

## 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}`--add-images` and {code}`--proxy-port` is used.

`````{tabs}

````{tab} Standard Upgrade

```{parsed-literal}
cd /tmp
curl -O {{ release_url }}
tar -xf {{ release_url.split('/') | last }}
sudo bash kasm_release/upgrade.sh --add-images --proxy-port 443
```

````

````{tab} Offline Upgrade x86-64

```{parsed-literal}
cd /tmp
curl -O {{ release_url }}
curl -O {{ amd_service_images_url }}
curl -O {{ amd_workspace_images_url }}
tar -xf {{ release_url.split('/') | last }}
sudo bash kasm_release/upgrade.sh --add-images --proxy-port 443 --offline-workspaces /tmp/{{ amd_workspace_images_url.split('/') | last }} --offline-service /tmp/{{ amd_service_images_url.split('/') | last }}
```

````

````{tab} Offline Upgrade arm64

```{parsed-literal}
cd /tmp
curl -O {{ release_url }}
curl -O {{ arm_service_images_url }}
curl -O {{ arm_workspace_images_url }}
tar -xf {{ release_url.split('/') | last }}
sudo bash kasm_release/upgrade.sh --add-images --proxy-port 443 --offline-workspaces /tmp/{{ arm_workspace_images_url.split('/') | last }} --offline-service /tmp/{{ arm_service_images_url.split('/') | last }}
```

````

`````

## 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} 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 `--offline-workspaces <KASM_WORKSPACE_IMAGES_TAR> --offline-service <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
```
______________________________________________________________________

**Add Connection Proxy Settings to Database**

When upgrading from a version <= 1.11.0 to >= 1.12.0 add connection proxy settings to the database:

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

- Start the Kasm services

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

```{include} upgrade_images.md
```