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.
- Install Chocolatey to simplify package management (not required; if not going with Chocolatey you have to install corresponding packages yourself). Chocolatey installation instructions: https://chocolatey.org/install
Install Java, Java is a prerequisite to run the groovy deployment helper script. Use the following Chocolatey command to install it:
CODEchoco install openjdk8
Install Groovy, a deployment helper script in groovy is available to help you deploy the iText DITO Manager container cluster. Ton install groovy, run the following Chocolatey command:
CODEchoco install groovy
- Install Docker. Note that regular Docker Desktop is not supported on Windows Server, but there are dedicated Windows Server-ready versions. For more details, see https://docs.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=Windows-Server
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):
- Find the path of the volume on the actual file system:
docker volume inspect dito-manager-db
. See "Mountpoint" section in the result. - View current permissions for the path on the system:
icacls C:\\ProgramData\\docker\\volumes\\dito-manager-db\\_data
- 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
- 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