Docker

Docker is a set of products that uses operating-system-level virtualization to develop and deliver software in packages called containers.

Docker containers run on all modern platforms (Windows 10, Windows Server 2016/2019, macOS 10.12+, Linux kernel 3.10 or higher), and there are various container runtimes available. Docker containers are also supported on basically any cloud host (AWS, Google Cloud, Azure, DigitalOcean, and more).

Docker containers can be based on Windows or Linux. PSPDFKit Server is a Linux-based Docker container. We suggest using a modern Linux-based distribution or a cloud provider to run PSPDFKit Server.

The most common way to run a Docker container is via Docker Engine. Docker Engine is the industry-leading container runtime. Mirantis offers a free community version and a commercial enterprise version. The enterprise version is needed when you’re deploying on Windows and/or if your business requires an SLA support agreement. Contact Mirantis for pricing information.

Running Docker as a Developer

The simplest way to run Docker during development is via Docker Desktop, which is available for macOS 10.13+ and Windows 10 1709 or higher.

Running Docker on Linux (Debian, Ubuntu, Red Hat…)

Docker containers are fully supported on Linux. See Docker’s official installation documentation. For most use cases, you’ll also want to install docker-compose to create containers.

If you’re using Docker EE, check out the Docker Compatibility Matrix to see if your Linux distribution is supported.

Running Docker in the Cloud

Docker containers are supported by all major cloud providers.

For deployment in production, we recommend using Kubernetes or native Docker implementations by cloud providers like Amazon Web Services, Google Cloud, or Microsoft Azure.

Running Docker on Windows 10 (Home or Professional)

Microsoft supports running Linux-based Docker containers via Windows Subsystem for Linux 2 (WSL 2).

Installing Windows Subsystem for Linux

The WSL 2 feature requires running Windows 10, version 1903 or higher.

We recommend you update Windows 10 to at least version 2004. However, Microsoft also backported WSL 2 to Windows 1903 and 1903 for x64 systems. Make sure to install the necessary updates. To summarize, if your minor build number is 1049 or higher on Windows builds 18362 or 18363, then you have the backport and the ability to run WSL 2 distros.

ℹ️ Note: Verify your Windows version by selecting the Windows logo key + R, typing winver, and selecting OK.

Windows 10 Version Window

Open PowerShell as Administrator and run:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Enable the Virtual Machines optional component:
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

You need to update the WSL 2 Linux kernel next via downloading the latest WSL 2 Linux kernel.

ℹ️ Note: To download files using just the PowerShell command line, use the following syntax: `Invoke-WebRequest -Uri “https://website.com/file.exe” -OutFile “C:\file.exe”

Make sure to reboot after the installation. To reboot via PowerShell, use Restart-Computer. Now make sure any new Linux distro you use is running WSL 2: wsl --set-default-version 2

Restart your machine to complete the WSL install and update to WSL 2. After the reboot, you can test if WSL 2 works by opening the Microsoft Store application and searching for your favorite Linux distro (e.g. Ubuntu 20.04).

Installing Docker For Windows

Install Docker for Windows to have a simple interface for managing containers. Starting with Docker Desktop Stable 2.3.0.2, Docker will use WSL 2 to run containers on it directly, offering higher performance than its Hyper-V counterpart.

ℹ️ Note: Older versions of Docker for Windows or older Windows version use Hyper-V and have limited support for running Linux-based Docker containers (using LCOW). Make sure to update to a recent version to get full compatibility with Linux Docker containers.

Running Docker on Windows Server 2016/2019

⚠️ Warning: We currently don’t recommend using Windows Server to run the PSPDFKit Docker container. This is because you might run into compatibility issues until Microsoft and Docker complete support for WSL 2.

Windows Server requires Docker Enterprise edition instead of Docker for Windows. Docker Enterprise (Windows Server) is available at no additional cost to all Windows Server 2019 and 2016 customers.

Open a PowerShell command prompt, and type the following commands:

Copy
1
2
3
4
5
6
7
8
Install-WindowsFeature -Name Hyper-V,Containers -IncludeAllSubFeature -IncludeManagementTools
Install-Module DockerMsftProvider -Force
Install-Package Docker -ProviderName DockerMsftProvider -Update -Force
Restart-Computer
[Environment]::SetEnvironmentVariable(“LCOW_SUPPORTED”, “1”, “Machine”)
Set-Content -Value "`{`"experimental`":true`}" -Path C:\ProgramData\docker\config\daemon.json
restart-service docker
Download https://github.com/linuxkit/lcow/releases/download/v4.14.35-v0.3.9/release.zip. unpack contents into C:/Program Files/Linux Containers

To run examples, you also need docker-compose:

Copy
1
2
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-WebRequest "https://github.com/docker/compose/releases/download/1.26.2/docker-compose-Windows-x86_64.exe" -UseBasicParsing -OutFile $Env:ProgramFiles\Docker\docker-compose.exe

Run docker info and ensure you see following line: Storage Driver: windowsfilter (windows) lcow (linux)

⚠️ Warning: Microsoft is deprecating support for Linux-based Docker containers via LCOW (Linux Containers on Windows) in favor of WSL 2, as WSL 1 (LCOW) has various compatibility issues. WSL 2 is a complete redesign that doesn’t share any of the issues of WSL 1.

The installation is similar to Windows Server 2019; however, you might need to update more components.

As an alternative, Docker Toolbox will work on both Windows Server and consumer Windows versions. Toolbox is primarily a development tool and lacks advanced monitoring for reliable hosting. Using a virtual machine with a recent Linux distribution to run the Docker container is also a possibility.

⚠️ Warning: Docker Community Edition (CE) requires Microsoft Windows 10 Professional or Enterprise 64-bit. There are various ways to work around this restriction. but we discourage you from using them for anything other than development purposes.

Running Docker on Virtualized Windows

If you provide your solution via a Windows virtual machine, you can still run Docker. Docker for Windows (Docker Engine) requires Hyper-V, which is supported by some virtualization products. While Oracle VirtualBox doesn’t support nested virtualization, VMware Workstation and Parallels do support this feature (see this tutorial for information on how to enable Hyper-V on VMware).

If Hyper-V is not available for your setup, you can choose Docker Toolbox, which doesn’t require a hypervisor to run.

Other Technologies

Docker Toolbox is a legacy runtime for older Mac and Windows systems and it doesn’t require Hyper-V (Windows) or hypervisor kit (Mac) to run. It uses VirtualBox under the hood, which is slightly slower than the modern Docker Engine. Docker Toolbox runs on Windows Server 2016/2019 and Windows 7/8/8.1/10.