---
myst:
  html_meta:
    "description lang=en": "Using a remote standalone PostgreSQL/Redis database installation and upgrade instructions. "
    "keywords": "Kasm, How to, How-to, Remote Database, Remote, External, PostgreSQL, Redis"
    "property=og:locale": "en_US"
---
```{title} Standalone Remote Database
```

# Standalone Remote Database

Admins may wish to use a Managed Database Service such as RDS and Elasticache or have a separate PostgreSQL Database and Redis server from their Kasm installation.

This guide provides instructions on how to initialize the database server from a remote machine and then install the Kasm WebApp.

## Requirements

- Remote PostgreSQL server supports PostgreSQL version 12.
- Remote PostgreSQL either already has a User "kasmapp" in the database "kasm" **OR** you have SuperUser credentials on the database.
- Remote Redis server supports Redis version 5.
- Machine executing initialization and the Web App server can both connect to the PostgreSQL Database (default port TCP/5432)
- Web App servers can connect to Redis Server (default port TCP/6379)
- Remote PostgreSQL must support the UUID-OSSP Extension. The Kasm installer will attempt to create the extension, if it is not already enabled.

```{important}
If you are using the **Azure Database for PosgreSQL** PaaS, you will need to enable the UUID-OSSP extension from the Azure portal prior to following the below steps. In the Azure portal, navigate to your Postgres database, go to Server Parameters, search for `azure.extensions`, hit the drop-down and check th box next to UUID-OSSP. Hit the Save button to apply the change. Wait for the change to apply, this can take a few minutes.
```

## When performing an installation

### Initializing PostgreSQL Server

- This can be done from anywhere, but since the script will install docker and other Kasm prerequisites it may be easiest to run the remote DB install from the future Kasm Web App server.
- Download latest version of Kasm Workspaces to /tmp
- Extract package and initialize the Database.

```{parsed-literal}
cd /tmp

curl -O {{ release_url }}

tar -xf kasm_release*.tar.gz

sudo bash kasm_release/install.sh \\
--accept-eula \\
--role init_remote_db \\
--db-hostname [DATABASE_HOSTNAME] \\
--db-password [DATABASE_KASMAPP_USER_PASSWORD] \\
--database-user [DATABASE_USERNAME] \\
--database-name [DATABASE_NAME] \\
--db-master-user [DATABASE_SUPERUSER_USERNAME] \\
--db-master-password [DATABASE_SUPERUSER_PASSWORD]
```

```{note}
If the Database already has the **User** "kasmapp" and **database** "kasm" created you may omit the `-g` and `-G` parameters. The **DATABASE_USERNAME** and **DATABASE_NAME** are optional and only required if not using the default kasm/kasmapp settings.
```

### Installing Kasm Web App

- Download latest version of Kasm Workspaces to /tmp
- Extract package and initialize the Database.

```Bash
cd /tmp

tar -xf kasm_release*.tar.gz

sudo bash kasm_release/install.sh \
--role app \
--db-hostname [DATABASE_HOSTNAME] \
--db-password [DATABASE_KASMAPP_USER_PASSWORD] \
--database-user [DATABASE_USERNAME] \
--database-name [DATABASE_NAME] \
--redis-hostname [REDIS_HOSTNAME] \
--redis-password [REDIS_PASSWORD]
```

```{note}
If you are using Redis on Elasticache you will need to set `[REDIS_PASSWORD]` to `""`.
```

### Backing up the PostgreSQL Server

- This script should be run from a Kasm Web App server.

If you are backing up a standalone remote database for Kasm Workspaces 1.10.0 we will need to use the backup script that is included with the {{ release }} release as the one included with 1.10.0 did not support a remote standalone database:

- Download the latest version of Kasm Workspaces to /tmp
- Extract package and run the backup script

```Bash
cd /tmp

tar -xf kasm_release*.tar.gz

sudo bash kasm_release/bin/utils/db_backup \
--backup-file [DESIRED_BACKUP_FILE_LOCATION] \
--database-hostname [DATABASE_HOSTNAME] \
--database-user [DATABASE_USERNAME] \
--database-name [DATABASE_NAME] \
--path [PATH_TO_KASM_INSTALL]
```

If you are backing up a standalone remote database for Kasm Workspaces 1.11.0 or newer then use the existing db_backup script:

```Bash
sudo bash /opt/kasm/bin/utils/db_backup -v --backup-file [DESIRED_BACKUP_FILE_LOCATION] -q [DATABASE_HOSTNAME] --path [PATH_TO_KASM_INSTALL]
```

- The backup will be present at the location specified with **--backup-file**

### Restoring the PostgreSQL server from a backup

- This script should be ran from a Kasm Web App server or during a Kasm Workspaces upgrade from the server that ran the database clean install step.
- You will need SuperUser credentials on the database.
- Make sure that All Kasm Web App and Agent servers have their services stopped.

```{parsed-literal}
sudo bash /opt/kasm/{{ release }}/bin/utils/db_restore \\
--backup-file [LOCATION_OF_BACKUP_FILE] \\
--database-hostname [DATABASE_HOSTNAME] \\
--database-user [DATABASE_USERNAME] \\
--database-name [DATABASE_NAME] \\
--path /opt/kasm/{{ release }} \\
--database-master-user [DATABASE_MASTER_USER] \\
--database-master-password [DATABASE_MASTER_USER_PASSWORD]
```

- After the restore is complete restart all Kasm Web App and Agent services.


## When performing an upgrade

```{important}
Before performing an upgrade ensure all Kasm Workspaces Containers/Sessions are stopped on all hosts in your deployment. `sudo /opt/kasm/bin/stop`
Also ensure the "Automatically Enable Agents" is enabled under settings in the Admin Dashboard.
These instructions are for upgrading from Kasm Workspaces >= 1.11.0 to {{ release }}.
```

### Upgrading Kasm Web App

#### Database migration

```{note}
The database migration commands should be run once from the Kasm Web App with access to the remote database. Any additional Kasm Web App server does not need to execute database migrations again.
```

* Stop all services:

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

* Grab and extract the installer for {{ release }}:

```{parsed-literal}
cd /tmp

curl -O {{ release_url }}

tar -xf kasm_release*.tar.gz
```

* Generate a database backup:

```{parsed-literal}
sudo mkdir -p /opt/kasm/backups/

sudo bash kasm_release/bin/utils/db_backup \\
--backup-file /opt/kasm/backups/{{ previous_release }}_backup.tar \\
--database-hostname [DATABASE_HOSTNAME] \\
--database-user [DATABASE_USERNAME] \\
--database-name [DATABASE_NAME] \\
--path /opt/kasm/current
```

* Log into your PostgreSQL server as the master user and remove the database/user:

```Bash
drop database if exists kasm;
drop user if exists kasmapp;
```

* Init the empty DB, restore our backup, and upgrade the database: 

```{parsed-literal}
sudo bash kasm_release/install.sh \\
--accept-eula \\
--role init_remote_db \\
--db-hostname [DATABASE_HOSTNAME] \\
--db-password [DATABASE_KASMAPP_USER_PASSWORD] \\
--database-user [DATABASE_USERNAME] \\
--database-name [DATABASE_NAME] \\
--db-master-user [DATABASE_MASTER_USER] \\
--db-master-password [DATABASE_MASTER_USER_PASSWORD]

sudo bash /opt/kasm/{{ release }}/bin/utils/db_restore \\
--backup-file /opt/kasm/backups/{{ previous_release }}_backup.tar \\
--database-hostname [DATABASE_HOSTNAME] \\
--path /opt/kasm/{{ release }} \\
--database-master-user [DATABASE_MASTER_USER] \\
--database-user [DATABASE_USERNAME] \\
--database-name [DATABASE_NAME] \\
--database-master-password [DATABASE_MASTER_USER_PASSWORD]

sudo bash /opt/kasm/{{ release }}/bin/utils/db_upgrade \\
--database-hostname [DATABASE_HOSTNAME] \\
--path /opt/kasm/{{ release }}
```

* Seed the new images for this installation:

```{parsed-literal}
sudo /opt/kasm/{{ release }}/bin/utils/db_init \\
--database-hostname [DATABASE_HOSTNAME] \\
--seed-file /opt/kasm/{{ release }}/conf/database/seed_data/default_images_amd64.yaml
```

#### Kasm Web App upgrade

* Run a clean install of {{ release }}:

```{parsed-literal}
sudo bash kasm_release/install.sh \\
--role app \\
--no-start \\
--db-hostname [DATABASE_HOSTNAME] \\
--db-password [DATABASE_KASMAPP_USER_PASSWORD] \\
--database-user [DATABASE_USERNAME] \\
--database-name [DATABASE_NAME] \\
--redis-password [REDIS_PASSWORD] \\
--redis-hostname [REDIS_HOSTNAME] \\
--skip-connection-test
```

* Update config information: 

```{parsed-literal}
export MANAGER_ID=$(/opt/kasm/bin/utils/yq_$(uname -m) '.manager.manager_id' /opt/kasm/{{ previous_release }}/conf/app/api.app.config.yaml)

sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.manager.manager_id = "'${MANAGER_ID}'"' /opt/kasm/{{ release }}/conf/app/api.app.config.yaml
```

* **Advanced**: Review the contents of the existing configs to ensure any custom docker settings are migrated to the new configuration.

```Bash
diff /opt/kasm/{{ previous_release }}/docker/docker-compose.yaml  /opt/kasm/{{ release }}/docker/docker-compose.yaml
```

* Start the Kasm Web App:

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

### Upgrading Kasm Agent

* Stop all services:

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

* Grab and extract the installer for {{ release }}:

```{parsed-literal}
cd /tmp

curl -O {{ release_url }}

tar -xf kasm_release*.tar.gz
```

* Execute a clean install:

```Bash
sudo bash kasm_release/install.sh \
--role agent \
--no-start \
--public-hostname [AGENT_HOSTNAME] \
--manager-hostname [MANAGER_HOSTNAME] \
--manager-token [MANAGER_TOKEN]
```

* Update config information:

```{parsed-literal}
export SERVER_ID=$(/opt/kasm/bin/utils/yq_$(uname -m) '.agent.server_id' /opt/kasm/{{ previous_release }}/conf/app/agent.app.config.yaml)

sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.agent.server_id = "'${SERVER_ID}'"' /opt/kasm/{{ release }}/conf/app/agent.app.config.yaml
```

* Copy the auto-generated nginx configs for any sessions that may exists on the Agent:

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

* **Advanced**: Review the contents of the existing configs to ensure any custom docker settings are migrated to the new configuration.

```{parsed-literal}
diff /opt/kasm/{{ previous_release }}/docker/docker-compose.yaml  /opt/kasm/{{ release }}/docker/docker-compose.yaml

diff /opt/kasm/{{ previous_release }}/conf/app/agent.app.config.yaml  /opt/kasm/{{ release }}/conf/app/agent.app.config.yaml
```

* Start the Kasm Agent:

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

### Upgrading/Adding the Guac Role

```{note}
This service is used to connect to VM/Hardware running RDP, VNC, or SSH. If these capabilities are not needed, this role does not need to be installed.
```

* On a new server Grab and extract the installer for {{ release }}:

```{parsed-literal}
cd /tmp

curl -O {{ release_url }}

tar -xf kasm_release*.tar.gz
```

* Login to the Workspaces UI as an administrator. Retrieve the value of **Component Registration Token** from the Global Settings.

* Execute a clean install:

```Bash
sudo bash kasm_release/install.sh \
--role guac \
--api-hostname [API_HOSTNAME] \
--public-hostname [GUAC_SERVER_HOSTNAME] \
--registration-token [COMPONENT_REGISTRATION_TOKEN]
```