From Version 5

Please ensure you are on version of 5.7 or higher of WorkSpaces Manager before upgrading. If you require assistance to upgrade to 5.7, please reach out to [e-mail] or contact your technical account manager.

Before proceeding with the upgrade procedure, ensure the following prerequisites are met:

1. Access to the EC2 Instance: You have access to the EC2 instance where WorkSpaces Manager (WSM) is configured.

2. IIS Webserver Configuration: The IIS Webserver is correctly configured and functioning.

3. Administrative Privileges: Administrative privileges on the EC2 instance are available.

4. Access to MS-SQL Instance and Database: Ensure valid access to the MS-SQL instance and the associated database.

5. EC2 Instance Role Permissions: The EC2 instance role must have sufficient permissions to read from AWS Secrets Manager.

6. SSL Certificate: A valid SSL certificate is available, especially if you are using HTTPS for secure communication.

7. .NET Core 8 (Hosting Bundle): .NET Core 8 (Hosting Bundle) is installed on the server.

8. AWS CLI v2: It is recommended to have AWS CLI v2 installed for interacting with AWS services from the command line.

Ensuring these prerequisites are met will help ensure a smooth and successful upgrade process.

Create PortalCore directory on D:

Log in to the EC2 instance where WorkSpaces Manager (WSM) is configured using your preferred method, such as RDP or AWS Session Manager Fleet Manager, depending on your network configuration and access settings.

Once connected:

1. Open File Explorer.

2. Navigate to the D: drive.

3. Create a new folder and name it PortalCore.

This folder will be used for the next steps in the upgrade process.

If you prefer to use PowerShell via the command-line as an administrator, you can use the following command to create the folder:

New-Item -Path "D:\PortalCore" -ItemType Directory

This command will create the PortalCore folder on the D: drive.

Stop Portal Website

To create the PortalCore website and application pool, follow these steps:

1. Open IIS Manager:

   • On the EC2 instance, open IIS Manager from the Start menu or by typing inetmgr in the Run dialog.

2. Locate the Portal Site:

   • In the left-hand panel of IIS Manager, expand the Sites node to locate the Portal site.

3. Stop the Portal Site:

   • Select the Portal site.

   • In the right-hand Actions panel, click Stop to temporarily stop the site.

This ensures that the Portal site is stopped before making further changes to configure the PortalCore website and application pool.

To stop an IIS website called "Portal" using PowerShell, you can use the Stop-Website cmdlet:

Stop-Website -Name "Portal"

Create PortalCore Website and Application Pool

To add the PortalCore website in IIS Manager, follow these steps:

1. Open IIS Manager: Ensure you're in IIS Manager.

2. Add a New Website:

   • Right-click on Sites in the left-hand panel.

   • Select Add Website.

3. Configure the New Website:

   • Site Name: Set the site name to PortalCore.

   • Physical Path: Set the physical path to the newly created PortalCore folder on the D: drive (D:\PortalCore).

   • Port and other bindings: Configure the bindings as necessary for your environment (e.g., HTTP or HTTPS).

4. Stop the PortalCore Site:

   • Select the newly created PortalCore site from the left-hand panel.

   • In the right-hand panel, click Stop to temporarily stop the site.

This will prepare the PortalCore website for further configuration and deployment.

To ensure the Identity for the PortalCore instance in the IIS application pool is set to LocalSystem, follow these steps:

1. Open IIS Manager: If you're not already in IIS Manager, open it.

2. Go to Application Pools:

   • In the left-hand panel, select Application Pools under your server.

3. Locate the PortalCore Application Pool:

   • Find the PortalCore application pool in the list.

4. Check the Identity:

   • If the identity is not already set to LocalSystem, right-click on PortalCore and select Advanced Settings.

5. Edit the Identity:

   • In the Advanced Settings window, scroll down to the Identity field.

   • Click Edit next to the Identity field.

6. Set Identity to LocalSystem:

   • In the Application Pool Identity window, select LocalSystem from the dropdown menu.

7. Apply the Changes:

   • Click OK to confirm the selection.

   • Click OK again to apply the changes.

This will set the PortalCore application pool to use the LocalSystem account for its identity, ensuring appropriate permissions for running the application.

To create the Website and associated Application Pool via Powershell, you can use the scripts below:

# Variables
$siteName = "PortalCore"
$appPoolName = "PortalCore"
$physicalPath = "D:\PortalCore"
$bindingInformation = "*:80:"  # Adjust the port and hostname as needed

# Create the Application Pool
New-WebAppPool -Name $appPoolName

# Set the Identity of the Application Pool to LocalSystem
Set-ItemProperty IIS:\AppPools\$appPoolName -Name processModel.identityType -Value LocalSystem

# Create the Website
New-WebSite -Name $siteName -PhysicalPath $physicalPath -ApplicationPool $appPoolName -BindingInformation $bindingInformation

Add a Custom URL and HTTPS Binding

If you have a custom URL for WorkSpaces Manager (WSM), you will need to add the corresponding hostname and associate it with the appropriate SSL certificate. This ensures secure communication over HTTPS and that the custom URL is properly configured for the site.

If you've assigned a URL to the site, follow these steps to add bindings:

1. Select the PortalCore site in IIS Manager, then click Bindings in the right-hand Actions panel.

2. Verify that there is a binding for Port 80 (HTTP). If it's missing, add it.

3. Click Add to create a new binding:

   • Change the port to 443 for HTTPS.

   • Set the hostname (your custom domain).

   • Select the appropriate SSL certificate and ensure it’s valid by clicking View.

4. Click OK, then Close to finalize the changes.

Configure Authentication Mechanisms

Navigate back to PortalCore in IIS Manager. In the Security section, follow these steps:

1. Select Authentication.

2. Ensure that Anonymous Authentication is set to Enabled.

3. Confirm that Windows Authentication is Disabled.

This configuration ensures that users can access the site without needing Windows credentials.

To execute this via PowerShell or command-line, you'll need to import the IISAdministration module and run a few commands to interact with IIS. Follow these steps:

Import-Module IISAdministration

Set-WebConfigurationProperty -Filter "/system.webServer/security/authentication/windowsAuthentication" -PSPath "IIS:\Sites\PortalCore" -Name "enabled" -Value "False"

(Get-WebConfigurationProperty -Filter "/system.webServer/security/authentication/windowsAuthentication" -PSPath "IIS:\Sites\PortalCore" -Name "enabled").Value

Set-WebConfigurationProperty -Filter "/system.webServer/security/authentication/anonymousAuthentication" -PSPath "IIS:\Sites\PortalCore" -Name "enabled" -Value "True"

(Get-WebConfigurationProperty -Filter "/system.webServer/security/authentication/anonymousAuthentication" -PSPath "IIS:\Sites\PortalCore" -Name "enabled").Value

Download and Install AWS CLI v2

To download and install AWS CLI v2 on Windows, follow these steps:

1. Download AWS CLI v2:

   • Download and install AWS CLI v2 for Windows from the official AWS CLI v2 installation page: Install AWS CLI v2 for Windows.

2. Run the Installer:

   • Locate the downloaded AWSCLIV2.msi file and double-click it to start the installation.

   • Follow the on-screen prompts in the setup wizard to complete the installation.

3. Verify the Installation:

   • After installation, open Command Prompt or PowerShell.

   • Run the following command to verify the AWS CLI version:

   aws --version

This should return the installed version of AWS CLI v2, confirming that it's successfully installed. You can now use the AWS CLI to manage your AWS resources from the command line.

Download and Deploy WorkSpaces Manager (WSM) version 6

Download the most recent WSM ZIP file from the following link:

https://wsm.nuvens.co/stable

Extract the contents of the ZIP file and copy them into the PortalCore folder located on the D: drive.

To perform the download, extraction and copy operation via PowerShell, run the following commands:

Write-Host "Download WSM onto a Temp folder..."
powershell -NoProfile -ExecutionPolicy unrestricted -Command "(New-Object System.Net.WebClient).DownloadFile('https://nuvensworkspacesmanager.s3.eu-west-1.amazonaws.com/latest/beta/WSM.zip', 'C:\Windows\Temp\WSM.zip')"

Write-Host "Uncompress the Portal on its folder..."
Expand-Archive -LiteralPath C:\Windows\Temp\WSM.zip -DestinationPath D:\PortalCore

Configure Secrets for Database Access

To securely store your database credentials in AWS Secrets Manager in the same AWS region in which your WorkSpaces Manager appliance is running, follow these steps:

1. Navigate to the old Portal folder on the D: drive.

   • Locate and open the web.config file.

   • Retrieve the database username and password from the file.

2. Log in to your AWS Account and open Secrets Manager.

3. Click Store a New Secret.

4. Set the Secret Type to Other type of secret.

5. Choose the Key/Value pairs as Key/Value instead of Plaintext.

6. Enter the database credentials retrieved from the web.config file:

   • username: Your database username from web.config (e.g., NuvensDBA).

   • password: The password from the web.config file.

7. For the database configuration, enter the following details:

   • engine: sqlserver

   • dbname: PortalCore

   • port: 1433

   • host: Enter the IP address of the EC2 instance and the SQL instance name (e.g., localhost\SQLEXPRESS if SQL is running locally).

   • encrypt: true or false (if database is encrypted)

   • trustservercertificate: true or false (if database requires Trust Server Certificate to be enabled)

8. Complete the secret storage process by following the remaining prompts to securely save the credentials in AWS Secrets Manager.

9. Click next, set the Secret name i.e. prod/WSMv6 click Next and Store.

After entering the database credentials and configuration details, follow these steps to complete the process:

1. Click Next.

2. Set the Secret Name (e.g., prod/WSMv6).

3. Click Next to review your settings.

4. Once everything is verified, click Store to save the secret securely in AWS Secrets Manager.

Your database credentials are now securely stored and ready for use in WorkSpaces Manager.

Ensure that the role attached to the instance has the necessary permissions to read secrets from AWS Secrets Manager. You can verify this using AWS CLI v2.

To create a secret via command-line using AWS CLI v2, execute the following commands:

PowerShell

aws secretsmanager create-secret `
    --name "prod/WSMv6" `
    --description "prod/WSMv6" `
    --region "eu-central-1" `
    --secret-string '{\"username\":\"NuvensDBA\",\"password\":\"strongpassword123\",\"engine\":\"sqlserver\",\"port\":\"1433\",\"dbname\":\"PortalCore\",\"host\":\"localhost\\SQLEXPRESS\"}'

Linux Bash

aws secretsmanager create-secret --name prod/WSMv603 --description "prod/WSMv603" --region eu-central-1 --secret-string "{\"username\":\"NuvensDBA\",\"password\":\"strongpassword123\",\"engine\":\"sqlserver\",\"port\":\"1433\",\"dbname\":\"PortalCore\",\"host\":\"localhost\\\\SQLEXPRESS\"}"

Please note, to properly store multiple key/value pairs instead of plaintext data, the backslash character (\) is used as an escape character. Since there is a backslash in the "host" key (localhost\SQLEXPRESS), you will need to use two (\\) or four backslashes (\\\\) to represent a single one.

This will securely store the database credentials in AWS Secrets Manager. After executing the command, you can verify that the secret was created by visiting AWS Secrets Manager in the AWS Management Console or by using the following AWS CLI command:

aws secretsmanager get-secret-value --secret-id prod/WSMv6 --query SecretString --output text

Verify Access to AWS Secrets Manager from WSM Appliance

To verify that the role attached to a Windows EC2 instance has permissions to read secrets from AWS Secrets Manager using AWS CLI v2, follow these steps:

1. Open PowerShell:

   • Log into the EC2 instance via RDP.

   • Open PowerShell as an administrator and run command:

   • aws secretsmanager get-secret-value --secret-id prod/WSMv6

2. Verify Role Permissions Using AWS CLI v2:

   • Run a command in PowerShell to check if the instance can retrieve the secret from AWS Secrets Manager.

3. Expected Output:

   • If the permissions are correct, the command will return the secret’s value.

   • If the permissions are not sufficient, it will display an error message.

4. Add IAM Policy to the Instance Role (if needed):

   • If the role attached to the instance does not have sufficient permissions, add the appropriate policy to the role via the IAM Console with the following JSON:

   • {
       "Version": "2012-10-17",
       "Statement": [
         {
           "Effect": "Allow",
           "Action": [
             "secretsmanager:GetSecretValue",
             "secretsmanager:DescribeSecret"
           ],
           "Resource": "*"
         }
       ]
     }

5. Attach the Policy:

   • Go to IAM in the AWS Management Console.

   • Locate the role attached to your EC2 instance.

   • Attach the policy that allows access to Secrets Manager.

By running the AWS CLI v2 command on your Windows instance through PowerShell, you can confirm if the instance has the necessary permissions to access secrets.

Install .NET Core 8 (Hosting Bundle)

To ensure the WorkSpaces Manager appliance runs properly, the .NET Core 8.x runtime (Hosting Bundle) needs to be installed on your server. Follow these steps:

1. Download .NET Core Hosting Bundle:

   • Visit the official .NET download page and select the Hosting Bundle for .NET Core 8.x.

2. Run the Installer:

   • After downloading, open the installer and follow the on-screen instructions to install the .NET Core Runtime along with the required IIS integration components.

3. Verify the Installation:

   • To confirm the installation, open a command prompt and check the installed version of .NET Core.

   • dotnet --info

4. Restart IIS (if needed):

   • Once the installation is complete, restart IIS to ensure that all components are loaded properly.

   • iisreset

After completing these steps, the WorkSpaces Manager appliance will be ready to run with the required .NET Core components.

Set Environment Variables

On the server, follow these steps to access the environment variables:

1. Search for "Environment Variables":

   • In the Start Menu search bar, type "Environment Variables".

2. Open System Properties:

   • From the search results, click "Edit the system environment variables" to open the System Properties window.

3. Access Environment Variables:

   • In the System Properties window, click the "Environment Variables..." button at the bottom to view and edit the environment variables.

This will allow you to view and modify system and user environment variables.

Click on Advanced, then select Environment Variables at the bottom of the window.

Under System Variables, click New.

• Variable Name: WSMCORE_SECRET_KEY

• Variable Value: Enter the name of the secret you stored (e.g., prod/WSMv6).

Click OK to save the new environment variable.

Repeat the process to add a new environment variable.

• Variable Name: WSMCORE_REGION

• Variable Value: Enter the region of the secret you stored (e.g., eu-central-1).

Click OK to save the new environment variable.

To create the system environment variables via PowerShell, use the following commands:

[System.Environment]::SetEnvironmentVariable('WSMCORE_SECRET_KEY', 'prod/WSMv6', [System.EnvironmentVariableTarget]::Machine)

# Verify that the environment variable was created
Get-ChildItem Env:

[System.Environment]::SetEnvironmentVariable('WSMCORE_REGION', 'eu-central-1', [System.EnvironmentVariableTarget]::Machine)

# Verify that the environment variable was created
Get-ChildItem Env:

This will set the WSMCORE_SECRET_KEY environment variable with the value prod/WSMv6 and WSMCORE_REGION with the value eu-central-1. Verify its creation by listing all environment variables.

Create and Configure PortalCore Database in SQL Server Management Studio (SSMS)

Open SQL Server Management Studio:

1. Right-click on Databases and select New Database.

2. Set the Database Name to PortalCore.

3. For both Database file paths, point them to the new PortalCore folder.

Click OK to create the database.

• Navigate to Security:

  • In SQL Server Management Studio (SSMS), go to Security > Logins.

• Select NuvensDBA:

  • Find and right-click on NuvensDBA.

• User Mappings:

  • In the properties window, go to User Mappings.

• Select PortalCore Database:

  • Check the box for the PortalCore database.

• Assign db_owner Role:

  • Under the Database role membership section, assign the db_owner role.

• Click OK to apply the changes.

• Open Command Prompt:

  • Right-click Command Prompt and select Run as Administrator.

• Run the IIS Reset Command:

  • In the Command Prompt window, type the following command and press Enter:

iisreset

This will reset IIS to apply any changes made.

Configure Database for WSMv6

• Go back to IIS Manager:

  • In the IIS Manager window, select the PortalCore site.

• Start the Site:

  • Click Start in the right-hand Actions panel to start the PortalCore site.

• Open a Web Browser:

  • Navigate to http://localhost to access the PortalCore site.

• Build the Database:

  • Click the Build Database option on the site and wait for the process to finish.

• Complete the Setup:

  • Once the database build is complete, click Continue to proceed.

• Identify Connection Errors:

  • If you encounter any connection errors, they might be caused by misconfigured environment variables or missing roles for IIS.

• Recommended Reboot:

  • To resolve this, it's recommended to perform a healthy reboot of the system by running the following command in Command Prompt (as Administrator):

shutdown /r /f /t 0

Import Database (Optional)

If you have an existing portal instance running Version 5 on the same database server, follow these steps to import the database:

1. Enter Existing Database Names:

   • Provide the names of the databases that were used with your previous portal instance.

2. Import Databases:

   • Import the databases to continue using them with WorkSpaces Manager v6.

This step ensures that your existing data from version 5 is migrated and remains accessible in version 6.

1. Enter Administrator Account Details:

   • Fill in the necessary information to create the Administrator account (e.g., username, password, email).

   • Click the Create Account button to finalize the creation of the Administrator account and move you to the next step.

2. Click Continue:

   • Once the Administrator account is created, click Continue to proceed with the setup process.

1. Input Your License Key:

   • Enter the license key provided for Workspaces Manager.

2. Fill in the Required Information:

   • Complete all necessary fields to configure Workspaces Manager, such as server details, admin credentials, or any other settings.

3. Click "Create Configuration":

   • Once all the information is filled out, click "Create Configuration" to finalize the setup process.

1. Check for Confirmation:

   • If everything is configured correctly, a confirmation message will appear.

2. Click "Continue":

   • After the confirmation appears, click "Continue" to proceed to the next step.

1. Setup Complete:

   • The configuration process is now finished.

2. Click "Login":

   • Click the "Login" button to access the Workspaces Manager Portal and begin using the system.