Deploying iText DITO Manager on Windows Server

Intro

This article provides step-by-step instructions on how to deploy iText DITO Manager on Windows Server. iText DITO is run on Linux containers, so it takes a couple of extra steps to deploy it in a Windows Server environment. For this example implementation we used an Azure Standard_D2_v3 instance, Windows Server 2019 with container support.

Before you start

Make sure that your node supports nested virtualization, which is not supported by every node type on AWS/Azure/Google Cloud. Consult with your hosting provider for details. 

Fetch the version of your system to verify everything is ok:

> (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

Install prerequisites

The are five prerequisites for a carefree installation of iText DITO Manager on Windows Server. Four of those will be installed now, the fifth one, Docker Compose, will be installed after we have prepared Docker.

Prepare Docker for Linux containers

Because iText DITO is run on Linux containers, we need to prepare Docker accordingly:

[Environment]::SetEnvironmentVariable("LCOW_SUPPORTED", "1", "Machine")

$configfile = @"
{
    "experimental": true
}
"@

$configfile | Out-File -FilePath C:\ProgramData\docker\config\daemon.json -Encoding ascii -Force

Invoke-WebRequest -Uri "https://github.com/linuxkit/lcow/releases/download/v4.14.35-v0.3.9/release.zip" -UseBasicParsing -OutFile release.zip

Expand-Archive release.zip -DestinationPath "$Env:ProgramFiles\Linux Containers\."

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

With all necessary features enabled, restart Docker to apply the changes

restart-service *docker* 

Install Docker Compose

Run the following command to install the Docker-compose, the final prerequisite.

choco install docker-compose

Deploy iText DITO Manager with the Deployment Helper Script

With all prerequisites in place and our containers prepared, we can now start the actual deployment. First, download the helper script for the version you want to deploy. In the example below, we are deploying version 2.0.4.

Invoke-WebRequest -Uri https://repo.itextsupport.com/dito-deployment-scripts/2.0.4/Deploy-2.0.4.groovy -OutFile Deploy-2.0.4.groovy

Next, deploy the application with the deployment helper script. For more details on this step, see Deploy iText DITO Editor and Manager

groovy Deploy-2.0.4.groovy create-app-file
groovy Deploy-2.0.4.groovy create-config-file --admin-email=... --admin-password=...
groovy Deploy-2.0.4.groovy deploy

Troubleshooting

If you are having troubles setting up the application, please check the logs from the containers. 

If you have the following error coming from the DB container:

could not link file "pg_xlog/xlogtemp.33" to "pg_xlog/000000010000000000000001": Permission denied

Then you need to take the following steps to fix it:

For all the volumes (dito-manager-db, dito-editor-data):

1. Find the path of the volume on the actual file system:  docker volume inspect dito-manager-db. See "Mountpoint" section in the result.

2. View current permissions for the path on the system:  icacls C:\\ProgramData\\docker\\volumes\\dito-manager-db\\_data

3. Grant all the users write permissions to that folder (you can look for more precise permission set up):  icacls C:\\ProgramData\\docker\\volumes\\pg\\_data /grant Users:"(OI)(CI)F" /T

4. Double check that applied permissions have any effect:  icacls C:\\ProgramData\\docker\\volumes\\dito-manager-db\\_data

When this is done, restart your application with groovy Deploy-2.0.4.groovy stop and groovy Deploy-2.0.4.groovy start