# Configure WorkSpaces Manager
{% hint style="danger" %}
Join WorkSpaces Manager EC2 instance to Active Directory Domain. This is recommended for full functionaility.
{% endhint %}
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. **AWS CLI v2**: It is recommended to have **AWS CLI v2** installed for interacting with AWS services from the command line.
3. **Access to MS-SQL Instance and Database**: Ensure valid access to the **MS-SQL instance** and the associated database.
4. **EC2 Instance Role Permissions**: The EC2 instance role must have sufficient permissions to read from **AWS Secrets Manager**.
5. **Administrative Privileges**: Administrative privileges on the EC2 instance are available, to perform tasks such as joining the domain, configuring IIS, and creating environment variables.
6. **License Validation Endpoint**: Outbound HTTPS access to `https://nuvens.info` must be allowed during initial configuration to validate the WorkSpaces Manager license key.
7. **Secret Creation**: A secret must be created in **AWS Secrets Manager** to enable the application to securely connect to the database.
## Connect to Windows instance via RDP or Session Manager Fleet Manager
To connect to a **WorkSpaces Manager Windows instance** using **RDP** or **Session Manager Fleet Manager**, follow these steps:
{% tabs %}
{% tab title="Connect via RDP" %}
1. **Retrieve the Private IP Address**:
* Copy the **private IP** if you’re connecting through a VPN, a direct connection, a Jumpbox or a WorkSpace.
2. **Use Remote Desktop (RDP)**:
* Open the **Remote Desktop Connection** application on your computer.
* Enter the **IP address** of the instance.
* Use the **Administrator username** and **password** to log in.
* Click **Connect** to access the instance.
{% endtab %}
{% tab title="Connect via AWS Fleet Manager" %}
1. **Open Systems Manager**:
* In the **AWS Management Console**, navigate to **Systems Manager** > **Fleet Manager**.
2. **Locate the Instance**:
* In Fleet Manager, find the **WorkSpaces Manager** instance you want to access.
* Select the instance and click **Node Actions**, then choose **Connect with RDP client** if RDP access is configured.
3. **Session Manager Connection** (if using an SSM agent and permissions):
* If **Session Manager** is enabled, click **Connect** within Fleet Manager, and you’ll be able to manage the instance directly without needing an IP address or RDP client.
{% endtab %}
{% endtabs %}
These options allow you to access and manage the **WorkSpaces Manager** instance depending on your network setup and access preferences.
## Join WorkSpaces Manager instance to the Active Directory Domain
Before configuring **WorkSpaces Manager**, it is required to join it to an **Active Directory Forest**. This integration ensures that the manager can interact with user accounts, groups, and other resources within the directory, enabling full functionality and proper access control.
To join **WorkSpaces Manager** to an **Active Directory (AD)** domain, you have several options. Joining it to AD requires a **service account** with appropriate permissions. Here are some common methods:
{% tabs %}
{% tab title="System Properties on Windows" %}
* **Open System Properties** on the WorkSpaces Manager instance (right-click on **This PC** > **Properties** > **Change settings**).
* Under the **Computer Name** tab, click **Change** to join a domain.
* Enter the **domain name** and provide the **service account** credentials with permissions to add computers to the domain.
* Restart the instance to apply changes.
{% endtab %}
{% tab title="PowerShell Commands" %}
* Run PowerShell as an administrator on the WorkSpaces Manager instance.
* Use the `Add-Computer` cmdlet to join the instance to the AD domain:
```powershell
Add-Computer -DomainName "yourdomain.com" -Credential (Get-Credential)
```
* Enter the **service account** credentials when prompted.
* Restart the instance after joining the domain.
{% endtab %}
{% tab title="AWS Systems Manager (SSM)" %}
* If **AWS Systems Manager** is enabled, go to **Run Command** in the AWS Console.
* Use the **AWS-JoinDirectoryServiceDomain** document to join the WorkSpaces Manager instance to an AD domain managed by AWS Directory Service.
* Provide the **domain name**, **organizational unit (OU)**, and **service account** credentials.
* Systems Manager will handle the domain join and restart if needed.
{% endtab %}
{% endtabs %}
#### Required Permissions for the Service Account
The service account should have:
* Permissions to **join computers** to the AD domain.
* **Read** and **write** permissions within the **Organizational Unit (OU)** where the WorkSpaces Manager will reside.
* Access to **create computer objects** in AD, if necessary.
These methods allow you to join WorkSpaces Manager to your Active Directory domain, ensuring it can integrate with your existing user and resource structures.
## Connect to **SQL Server Management Studio (SSMS)**
{% hint style="danger" %}
To connect to the **PortalCore** database using **SQL Server Management Studio (SSMS)**, ensure you are logged in as a Windows Administrator, as the BUILTIN\Administrators group is enabled.
* For the **Server name**, leave the default hostname or use: `localhost\NUVENS`.
This configuration enables direct access to the SQL Server instance on the local machine, allowing you to manage the **PortalCore** database and its users effectively.
{% endhint %}
By default, an account is available for connecting to the database to begin initial configuration. Use the following details to connect:
* **Server name**: use `localhost\NUVENS`.
* **Authentication**: Windows Authentication.
Because the group BUILTIN\Administrators is part of the management setting of MS SQL, a local administrator will have access to the SQL Instance.
New Microsoft Connection Security requires to set an encryption level. Depending on the choise, this requires to have certificates installed, so if this issue is shown:
Make sure that **Encryption** is set to **Optional**:
Once connected to SQL Server Management Studio (SSMS):
1. In the **Object Explorer** panel on the left, locate the connected server instance.
2. Expand the **Databases** node by clicking the plus sign (`+`) next to it.
3. Scroll through the list to ensure the **PortalCore** database is present.
If the **PortalCore** database is not listed, it may require additional steps may be required to set it up.
## Recommended: change password for Database administrator
To change the password for the **NuvensDBA** account in the **PortalCore** database in **SQL Server Management Studio (SSMS)**, follow these steps:
1. **Open SQL Server Management Studio (SSMS)** and connect to your SQL Server instance.
2. **Navigate to Security**:
* In **Object Explorer**, expand the **Security** folder under the server level.
* Select **Logins**.
3. **Locate NuvensDBA**:
* Right-click on **NuvensDBA** and select **Properties**.
4. **Change Password**:
* In the **Login Properties** window, go to the **General** page.
* Enter the new password in the **Password** and **Confirm Password** fields.
5. **Click OK** to save the changes.
This updates the password for the **NuvensDBA** account in the **PortalCore** database.
## Optional: Download and Install AWS CLI v2
{% hint style="success" %}
The **AWS CLI** is a valuable tool for ensuring that **WorkSpaces Manager** has access to essential AWS endpoints. Nuvens recommends installing it on the same appliance.
{% endhint %}
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](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-windows.html).
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:
```powershell
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.
## 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. **Log in to your AWS Account** and open **Secrets Manager**.
2. Click **Store a New Secret**.
3. Set the **Secret Type** to **Other type of secret**.
4. Choose the **Key/Value pairs** as **Key/Value** instead of **Plaintext**.
5. Enter the database credentials:
* **username**: Your database username (e.g., NuvensDBA).
* **password**: The password assigned to the username.
6. 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\NUVENS` if SQL is running locally).
7. **Complete the secret storage process** by following the remaining prompts to securely save the credentials in **AWS Secrets Manager**.
8. 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.
{% hint style="warning" %}
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**.
{% endhint %}
To create a secret via command-line using **AWS CLI v2**, execute the following commands:
{% tabs %}
{% tab title="Microsoft 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\"}'
```
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\NUVENS`), you will need to use **two backslashes** (`\\`) to represent a single one.
{% endtab %}
{% tab title="Linux Bash" %}
```bash
aws secretsmanager create-secret --name prod/WSMv603 --description "prod/WSMv6" --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 **four backslashes** (`\\\\`) to represent a single one.
{% endtab %}
{% endtabs %}
This will securely store your 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:
```powershell
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:
* ```powershell
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 this error message.
4. **Add IAM Policy to the Instance Role**:
* 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:
* ```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.
## Set Environment Variables
On the server, follow these steps to access the environment variables and add two new ones:
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.
Click again **New**.
* **Variable Name**: `WSMCORE_REGION`
* **Variable Value**: Enter the code for the AWS Region where WSM is running (e.g., `eu-central-1)`.
Click **OK** to save the new environment variable.
This will set the `WSMCORE_SECRET_KEY` and `WSMCORE_REGION` environment variables with the right values, which we can verify by listing all environment variables executing the command:
{% tabs %}
{% tab title="Powershell" %}
```powershell
Get-ChildItem Env:
```
{% endtab %}
{% tab title="Command Prompt" %}
```bash
set
```
{% endtab %}
{% endtabs %}
To create the system environment variable via PowerShell, use the following commands:
```powershell
[System.Environment]::SetEnvironmentVariable('WSMCORE_SECRET_KEY', 'prod/WSMv6', [System.EnvironmentVariableTarget]::Machine)
[System.Environment]::SetEnvironmentVariable('WSMCORE_REGION', 'eu-central-1', [System.EnvironmentVariableTarget]::Machine)
# Verify that the environment variables were created
Get-ChildItem Env:
```
{% hint style="info" %}
During setup, WorkSpaces Manager attempts to determine the AWS region automatically. It first checks for environment variables (`WSMCORE_REGION`, `AWS_REGION`, or `AWS_DEFAULT_REGION`). If none are set, it retrieves the region from the EC2 instance metadata. If this cannot be determined, the system defaults to **us-east-1**.
{% endhint %}
## Reset Internet Information Service (IIS)
* **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
* **Open a Web Browser**:
* Navigate to [**http://localhost**](http://localhost) to access the PortalCore site.
* **Check for Database Connected**:
* Check to see if the database is connected if it is not you will see an option to **Build Database** click 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):
```powershell
shutdown /r /f /t 0
```
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.
{% hint style="danger" %}
During initial configuration, outbound HTTPS access to must be allowed to validate the WorkSpaces Manager license key.
{% endhint %}
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.
{% hint style="info" %}
On your first login navigate to Update, select WorkSpaces to push an update to retreive data quicker.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.nuvens.cloud/install/installation-procedure/configure-workspaces-manager.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.