PolySwarmPolySwarmPolySwarmPolySwarm
Help

Windows (Docker) Development Environment

Windows-Based Development Environment Using Docker & Hyper-V

Windows has recently added containerization facilities similar to those provided by the Linux kernel. Like Linux containers, Windows containers operating in process-isolation mode share their kernel and core operating system. This guide will walk you through creating Windows-based PolySwarm participants inside Docker containers.


システム要件

Make sure your system meets or exceeds the following requirements:

  • A physical computer running Windows Server or Windows 10 Pro / Enterprise, version 1809 or newer.
  • VT-x がサポートされ、BIOS で有効になっている
  • 8GB+ of RAM
  • 2+ CPU cores
  • 21GB+ disk space

These instructions are tested against:

  • Windows 10 Pro 1809 (17763.437)
  • Docker Desktop CE Version 2.0.0.3 (31259), Build: 8858db3

Using older versions may work, but have not been tested and will not be supported.

Some cloud providers such as Azure and Amazon support hosting guest Windows containers as well.


Getting Started

Install Hyper-V

We'll need Hyper-V, Microsoft's hypervisor, to:

  1. Develop our Windows-based PolySwarm participant (microengine or arbiter).
  2. Conduct integration tests (these tests require Linux virtual machines that will be hosted using Hyper-V).

To install Hyper-V, open an "elevated" / "privileged" PowerShell console:

  • search "PowerShell" in the desktop search bar
  • right click on "Windows PowerShell"
  • select "Run as administrator".

In the elevated PowerShell prompt, run:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All

Restart Windows.

Set Up Docker

  1. Register / log into Docker Hub
  2. Download Docker for Windows.
  3. Run the installer.

Detailed instructions for less common configurations can be found in the Docker documentation.

After installation is complete, run Docker Desktop, enable Container functionality if prompted, and log into your Docker Hub account.

Configure Docker for Windows Containers

Docker for Windows can either host Linux containers or Windows containers; it cannot host both at the same. Docker will default to Linux container mode; we'll need to switch to Windows container mode.

You can override the default setting during the installation process or at any time after installation using the Docker tray-menu (right-click the icon) and select "Switch to Windows containers...".

Switching to Windows container mode will require a host restart.

Verify that you're in Windows container mode by right-clicking the Docker tray-menu icon and looking for the "Switch to Linux containers..." option. If your menu still says "Switch to Windows containers..." then you have not successfully switched. There appears to be bugs in this switching process; you may need to try switching (and restarting) several times.

Process Isolation

Whenever possible, we strongly recommend running Windows containers in "Process Isolation" mode. Process Isolation causes Windows containers to share kernel resources with your host, akin to how Docker works on Linux, incurring far less overhead than Hyper-V based container virtualization.

You cannot use Process Isolation if:

  1. Your host Windows installation does not match the kernel version of the polyswarm-client-windows container (1809). We strongly recommend matching host and container versions where possible.
  2. Your participant (microengine, arbiter) requires the use of Windows kernel modules. We strongly recommend building participants without this requirement.

If you cannot use Process Isolation mode, omit --isolation=process from subsequent instructions to run the container using Hyper-V virtualization.

Pull & Run polyswarm-client-windows

Pull the polyswarm-client-windows image:

docker pull polyswarm/polyswarm-client-windows:latest

Test the polyswarm-client-windows image:

docker run --isolation=process -it polyswarm/polyswarm-client-windows powershell

Within the container, run Python and attempt to import polyswarmclient:

PS C:\> python
Python 3.6.7 (v3.6.7:6ec5cf24b7, Oct 20 2018, 13:35:33) [MSC v.1900 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import polyswarmclient
>>>

If you're able to import polyswarmclient within the container then your Docker setup is fully working. Run quit() to exit the Python prompt and then exit to exit and destroy the container.


Development Environment

This guide will assume that you'll be conducting development directly on your Windows host. This is the simplest configuration choice.

Advanced users might consider conducting development within a Windows Hyper-V VM, but configuring such a VM is left as an exercise to the reader.

Configure Script Execution

We'll need to use Administrator privilege to make several changes to default Windows settings. We'll need an "elevated" PowerShell console:

  • search "PowerShell" in the desktop search bar
  • right click on "Windows PowerShell"
  • select "Run as administrator".

Run the following in this privileged PowerShell prompt.

  1. Permit script execution (necessary for installing Chocolatey & using virtualenvs):
    Set-ExecutionPolicy Bypass -Scope LocalMachine -Force
    ```

2. Force PowerShell to use TLSv2 (required of some dependencies):

    ```powershell
    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
    ```


### Install Chocolatey & Prerequisites

Chocolatey is a package manager for Windows.
We'll use it to help with installing some prerequisites.

Run the following in an *elevated* PowerShell prompt.

1. Install Chocolatey:

    ```powershell
    iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
    ```

2. Use Chocolatey to install prerequisites (do these one at a time):

    ```powershell
    choco install -y git
    choco install -y python --version 3.6.7
    ```


### Disable Anti-Malware Products



<div class="warning">



&gt; We strongly recommend disabling all anti-malware products in your development environment - including the built-in Windows Defender.
&gt; Below, we describe disabling Windows Defender.
&gt; Disabling third party solutions is left as an exercise for the reader.



</div>



PolySwarm engines should expect to come into contact with malware.
Existing anti-malware engines, including the built-in Windows Defender, can easily get in our way, quarantining or deleting files during development.

You can disable Windows Defender by installing a verified configuration package from Chocolatey (make sure to do so in an elevated prompt):

```powershell
choco install -y disabledefender-winconfig

Reboot Windows.

If you need to re-enable realtime protection at any point in the future, you can uninstall the package

choco uninstall disabledefender-winconfig

and then reboot Windows.

Set up a Virtual Environment (virtualenv)

We strongly recommend that you create a PolySwarm virtualenv so as to keep the system-wide Python packages clean:

cd ~
python -m venv polyswarmvenv
./polyswarmvenv/Scripts/Activate.ps1

Install cookiecutter

If you're using a virtualenv (see above), ensure that you activate it before installing cookiecutter.

We'll use cookiecutter to customize the PolySwarm participant template to our needs:

pip install cookiecutter

Next Steps

これで、有効な開発環境が用意できました。では、以下の PolySwarm 参加者の開発に進みます。