Skip to main content

Troubleshooting Manager Deployment

This page describes possible problems and their solutions that a user may encounter when deploying Fluent Manager.

1. Insufficient privileges prevent the deployment script from running successfully​

While using the script, you may encounter problems like the one shown below

Problem

> kotlin fluent-deploy-docker-compose.main.kts deploy

docker: error during connect: In the default daemon configuration on Windows, the docker client must be run with elevated privileges to connect.: Post http://%2F%2F.%2Fpipe%2Fdocker_engine/v1.24/containers/create: open //./pipe/docker_engine: The system cannot find the file specified.

Solution: To solve the issue, you need to run the deployment script with elevated access. Depending on your privacy settings, administrator rights may be required to run the application deployment script. This is because the deployment script needs to access the docker process, which may be restricted by your system settings.

Make sure that the docker process is running and execute deployment with Administrator privileges on Windows systems, or with sudo utility on Unix.

2. Deployment Fluent Manager on Windows Server 2019​

Deployment is based on Windows Server 2019 with container support. Since Docker Desktop with WSL2 is not supported for Windows Server 2019, we use Docker Engine with the LCOW feature as a workaround.

caution

Node must support nested virtualization, which is not supported by every node type on AWS/Azure/Google Cloud. Consult with your hosting provider for details.

Steps:

  1. Fetching the version of your system to verify everything is ok (use PowerShell to execute commands):
> (Get-WmiObject -class Win32_OperatingSystem).Caption
Microsoft Windows Server 2019 Datacenter
> [Environment]::OSVersion
Platform ServicePack Version      VersionString
-------- ----------- -------      -------------
Win32NT             10.0.17763.0 Microsoft Windows NT 10.0.17763.0fsd
  1. Install Chocolatey to simplify package management.

Chocolatey installation instructions

info

Chocolatey installation is not required. However, if you choose to not go with Chocolatey you will have to install the corresponding packages yourself.

  1. Install Java (needed to run Kotlin scripts): 
choco install openjdk11
  1. Install Kotlin: 
choco install kotlinc
  1. Install Docker. Note that regular Docker Desktop is not supported on Windows Server, and you have to install a dedicated Windows Server ready version. Follow these details to install Docker on your server.

NOTE: You can download the following script to install Docker: 

Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/Windows-Containers/Main/helpful_tools/Install-DockerCE/install-docker-ce.ps1" -o install-docker-ce.ps1

After it’s available locally, you should open install-docker-ce.ps1 and change the following string: $version = $availableVersions[0] on $version=17.09.0-ce. After that you can use the script to install Docker CE:

.\install-docker-ce.ps1
caution

Not all Docker versions support the LCOW feature. It is marked as "experimental" for some of them. Please use Docker Engine versions starting from 17.x and lower or equal to 19.x. At the moment of writing this documentation (current Docker version is 23.0.6) this experimental function was removed. Please check the Docker documentation for your installation.

  1. Because Fluent Manager is run on Linux containers, we need to prepare Docker accordingly. Enable the LinuxKit system for running Linux containers:
[Environment]::SetEnvironmentVariable("LCOW_SUPPORTED", "1", "Machine")

Restart Docker:

Restart-Service docker
  1. Enable Experimental Features in Docker daemon.conf
$configfile = @"

{

    "experimental": true

}

"@

$configfile|Out-File -FilePath C:\ProgramData\docker\config\daemon.json -Encoding ascii -Force
  1. Since Linux Containers need a Linux kernel, we need to deploy LCOW for it to run:
Invoke-WebRequest -Uri "https://github.com/linuxkit/lcow/releases/download/4.14.29-0aea33bc/release.zip" -UseBasicParsing -OutFile release.zip
Expand-Archive release.zip -DestinationPath "$Env:ProgramFiles\Linux Containers\."
  1. Now we have to make sure that all the Windows Server features necessary to run Docker are enabled: 
Enable-WindowsOptionalFeature -Online -FeatureName containers –All
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V –All
Restart-Computer
  1. Install docker-compose:
choco install docker-compose
  1. Now we need to download our deployment script:
Invoke-WebRequest -Uri https://repo.itextsupport.com/artifactory/fluent-deployment-scripts/x.y.z/fluent-deploy-docker-compose-x.y.z.main.kts -OutFile fluent-deploy-docker-compose-x.y.z.main.kts

NOTE: Replace x.y.z on your prefered Manager version.

  1. Finally, run the application with the helper deployment script:
kotlin fluent-deploy-docker-compose-x.y.z.main.kts create-app-file
kotlin fluent-deploy-docker-compose-x.y.z.main.kts create-config-file --admin-email=admin@email.com --admin-password=long_pa$$word
kotlin fluent-deploy-docker-compose-x.y.z.main.kts deploy

NOTE: Check the Deploying Manager docs for more details about these steps.