Windows Deployment (Windows 11, not Server 2025)

To deploy Clarity Connect on Windows (Non-Server), you will use the Windows Subsystem for Linux (WSL). This process requires WSL so that your Windows system can run the linux kernel required for running linux based containers.

Before you begin

Prerequisites
Operating System: Windows 11 (bare metal or virtualized; if virtualized, nested virtualization must be enabled)
Hardware: Ensure virtualization is enabled in the BIOS.
Permissions: You will need the ability to run commands as Admin in Powershell

Please read above for considerations before you begin this process.

Installation Instructions

Step 1: Install Windows Subsystem for Linux (WSL)

To install WSL, you need to run the following command using an Administrator Powershell :  

https://learn.microsoft.com/en-us/windows/wsl/install

wsl --install

Step 2: Reboot your System

Reboot the Windows system to complete the WSL install.

Step 3: Install WSL Ubuntu Distro

Next we need to choose a distribution for WSL to use for running Docker.  Our suggestion, and the following instructions use Ubuntu as this option. Run the following command to isntall the Ubuntu distribution (see note about user creation below).
https://learn.microsoft.com/en-us/windows/wsl/install#change-the-default-linux-distribution-installed

wsl --install -d Ubuntu

Ubuntu User Creation

You may be required to create a user for Ubuntu install (see image above). By default it will suggest the username of your current logged in user.

Make sure to securely store the username and password of the user you create.

This will be called the Ubuntu Username below, if you create a different name than your logged in Windows User, please use the correct one in the steps below. (For ease of setup, I would make these Usernames the same)

Step 4: Check if systemd is enabled on boot

After the last step, you will now be logged into the Ubuntu OS running on WSL

Next we want to verify this Ubuntu install has systemd enabled correctly, this will allow the docker service to start automatically when the system reboots.

cat /etc/wsl.conf

The file should appear as below (additional user info beneath is fine (see image):

[boot]
systemd=true

Step 5: Install docker in Ubuntu

Use the Docker easy to use install method to install Docker and Docker Compose (otherwise you can install using this method: https://docs.docker.com/engine/install/ubuntu/)_:

https://get.docker.com/

https://github.com/docker/docker-install/

sudo apt-get update && sudo apt-get install -y curl
curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh
sudo service docker start

This warning below is expected, do not abort the install process.

Run the following commands to verify docker and docker compose are installed:

# this will display an unknown command error if its not installed properly
docker --version
# this will display an unknown command error if its not installed properly
docker compose version

Step 6: Verify Docker is configured to run at boot

The following commands setup docker to run at boot for the Ubuntu OS, as well as grant your Ubuntu User the ability to run docker commands.

# Set Docker to start automatically on boot
sudo systemctl enable docker

# Start the Docker service now
sudo systemctl start docker

# Add your user to the docker group (replace {Ubuntu Username} with your actual username)
sudo usermod -aG docker {Ubuntu Username}

Step 7: Retrieve your Clarity Connect Configuration file

See the following article for where to get/create your Clarity Connect file (docker-compose.yml): Configuring Clarity Connect (On-Premises)

Place your downloaded docker-compose.yml file into a permanent directory (e.g., C:\ClarityConnect\).

Note about your docker-compose file

Note: Your docker-compose.yml file contains sensitive data that allows ClarityConnect to make secure api calls. Do not share this file with anyone outside of your organization.

Step 8: Attempt to start the containers

Navigate in the Ubuntu shell to where you placed the docker-compose.yml file

Note that C:\ClarityConnect\  would be /mnt/c/ClarityConnect/

cd /mnt/c/ClarityConnect/

Now you can run the following command, to attempt to boot the containers:

# Use the local docker-compose.yml file, and run the containers
# -d flag means to run detached, your terminal window wont be required to stay open for containers to run
# By default this command looks in the current directory for a file named docker-compose.yml
docker compose up -d

Docker downloading the containers for the first time:

Containers created successfully:

Windows Scheduled Task

Next we need to setup a Scheduled Task in Windows so that when the computer (Windows OS) reboots for maintenance, updates, etc. the Clarity Connect service starts on its own after the reboot.

You may need to type exit to get out of the Ubuntu Shell, this should return you to the powershell command line.

Powershell Method

# This series of commands will create a Scheduled Task, to run wsl.exe, and add the arguments
# Make sure to replace the {variables} with the approrpiate values.

$cred = Get-Credential -UserName "{DEVICE_OR_DOMAIN-NAME\WINDOWS USER NAME}" -Message "Enter password"

$action = New-ScheduledTaskAction -Execute "wsl.exe" -Argument "-u {Ubunutu Username} sleep infinity"

$trigger = New-ScheduledTaskTrigger -AtStartup

Register-ScheduledTask -TaskName "Start-WSL-Docker" -Action $action -Trigger $trigger `
    -User $cred.UserName -Password $cred.GetNetworkCredential().Password -RunLevel Highest

The above powershell command will prompt you for a password for your Windows User:

Task Scheduler Interface

Make sure all values (especially for Usernames), match your host system (not the test system used to created this article).

You will be prompted for your Windows password after choosing the user in Security Options.

General:

Triggers:

Actions:

The program listed just shows wsl.exe, but the actual path is C:\Windows\System32\wsl.exe

Arguments: -u {Ubuntu Username} sleep infinity

Make sure to replace {Ubuntu Username} with the username you created in Step 3

Test Reboots

You should verify that the service is properly spinning up and communicating with you Clarity tenant after a full reboot cycle and when you shutdown, and reboot the system.

Visit the same page where you created and downloaded your Clarity Connect configuration file (docker-compose.yml) and you can use the Last Sync column to verify if the system is up and running without needing to log into the system.

https://YOUR_TENANT.claritysecurity.io/application/on-prem-setup

Last Sync Timer

Clarity Connect only checks in roughly every 60 seconds, this means you may need to refresh the page a few times.  Also keep in mind, it may take a few minutes for your Clarity Connect host to boot up, run the scheduled task, and finish spinning up the containers (at which point it may take an additional minute to check in).

Depending on your host system, its good to wait at least 5 min to verify if the containers spun up on their own, if after 5-10 minutes the Last Sync timestamp still has not updated, you may want to log in and test if the scheduled task is working as expected.

FAQ - Frequently Asked Questions

# Launch the WSL Ubuntu VM and open the shell (command line). This is automated on boot in the later steps.
wsl

# Shutdown the WSL VM
wsl --shutdown

Need help?