On-Prem Agent on Windows

The on-prem agent is a Linux-based Docker container, which naturally lends itself well to a Linux host. For ease of installation we recommend running the on-prem agent on a Linux host.

But, if for compliance or other reasons you are required to run the on-prem agent on a Windows host, you can. This document calls out considerations for installing the on-prem agent on a Windows host.

Installing Docker on a Windows host

You have several options for installing Docker on a Windows host.

1. You can run a Linux host in Windows Subsystem for Linux (WSL2), and run docker within WSL2. To install WSL2 on your Windows host, run

   wsl --install

   from PowerShell and follow the prompts. Once WSL2 is installed, assume the root user with sudo su and run

   apt update && apt upgrade -y

   Then, follow the steps on Docker's website to add Docker's aptitude repository and install the latest Docker packages. Additionally, install docker-compose with

   apt install docker-compose

   You can start the docker service as the root user with

   service docker start

2. You can download and install Docker Desktop for Windows. Note that depending on your company's size and other factors, you may need to license Docker Desktop. Please consult Docker's licensing information.

3. You can purchase and install the Mirantis Container Runtime Docker engine.

Ensuring containers run on boot on a Windows host

By default, WSL2 and Docker Desktop are not launched until a user has logged in to the Windows host. This makes maintenance difficult - a system that reboots does not automatically launch WSL2 or Docker Desktop without a manual login. But you can use Windows scheduled tasks to ensure that WSL2 or Docker Desktop start automatically.

note

Regardless of if you use WSL2, Docker Desktop, or another Docker service on your Windows host, please remember to mark your on-prem agent as restart: always, and run docker compose in "detached" mode (i.e. docker-compose up --detach) For example,

docker-compose.yml

services:
  on-prem-agent:
    image: prismaticio/on-prem-agent:latest
    environment:
      PRISMATIC_URL: https://app.prismatic.io
      APP_PORT: 1433
      APP_HOST: 10.0.0.123
      NAME: Acme MS SQL
      REGISTRATION_JWT: eyJ0eXAiOiJK...
    restart: always # Use "always" to start this service when the Docker engine starts

To create a new scheduled task, search for "Task Scheduler" from your Windows search bar.

Then, select Action > Create Task

Within the scheduled task, ensure that Run whether user is logged on or not and Run with highest privileges are selected. Give the task an identifiable name and select an appropriate version of Windows for your installation.

Configuring Docker Desktop to run on boot

Within a new scheduled task's Triggers tab, create a new trigger to begin the task At startup. Set the Delay task for to 1 minute and ensure Enabled is selected.

Under the Actions tab, create a new action and start the program "C:\Program Files\Docker\Docker\Docker Desktop.exe"

After rebooting your Windows host, you should see Docker Desktop and any containers marked restart: always automatically start without user login within a few minutes.

Ensuring WSL2 to run on boot

Within a new scheduled task's Triggers tab, create a new trigger to begin the task At startup. Set the Delay task for to 1 minute and ensure Enabled is selected. Additionally set Repeat task every to every couple of minutes for the first 15 minutes. HyperV may not be ready to start the Docker service one minute after boot and the additional task repeats helps to ensure that the task completes eventually.

Under the Actions tab, create a new action and start the program "C:\Program Files\WSL\wsl.exe". Under Add arguments (optional) include the arguments:

-u root -e sh -c "service docker status || service docker start"

This instructs your machine to run wsl.exe on boot, and as the root user it will start the docker service if it is not already running. After rebooting your Windows host, you should see WSL, its Docker service, and any containers marked restart: always automatically start without user login within a few minutes.