.. _InstallWin: [Best effort] Installing GEOS on Windows machines using Docker ================================================================= In this section, we will install GEOS on a Windows machine using a ``Docker`` container with a precompiled version of GEOS's third party libraries (TPL). These steps are an adaptation of `ref:UsingDocker` for the Windows environment. In the following sections, we will be using *Ubuntu* based image as an example. 1. Install *Docker Desktop* ---------------------------- On your Windows machine, follow these `steps `_. Download the most recent installer for *Docker Desktop*. Before installation please check the current status of Windows Subsystem for Linux ( ``WSL`` ) on your machine as ``Docker`` will use ``WSL2`` as a `backend `_. To do that, open a ``PowerShell(Admin)`` .. PS admin .. code:: shell PS > wsl --install PS > wsl --status PS > wsl --set-default-version 2 PS > wsl --status The first command should install *WSL2*, download an *Ubuntu* distribution for it and ask for a restart. The following commands are used to check the status, and if the ``WSL`` is still the default one, change it to ``WSL2``. More details on the installation procedure can be found `here `_. Once the ``WSL2`` is set as default, proceed with the *Docker Desktop* installation. 2. Start *Docker Desktop* ---------------------------- When launching Docker Desktop for the first time, you should be prompted with a message informing you that it uses ``WSL2``. Using ``PowerShell``, you can check that ``Docker`` and ``WSL2`` are actually running in the background: .. code:: shell PS > Get-Process docker Handles NPM(K) PM(K) WS(K) CPU(s) Id SI ProcessName ------- ------ ----- ----- ------ -- -- ----------- 123 11 26084 25608 0.42 13960 1 docker PS > Get-Process wsl Handles NPM(K) PM(K) WS(K) CPU(s) Id SI ProcessName ------- ------ ----- ----- ------ -- -- ----------- 146 8 1412 6848 0.05 14816 1 wsl 146 7 1356 6696 0.02 15048 1 wsl 145 7 1368 6704 0.02 15100 1 wsl 145 7 1352 6716 0.14 15244 1 wsl 146 7 1396 6876 0.02 16156 1 wsl You should be able to see one docker process and several *wsl* processes. 3. Preparing *DockerFile* -------------------------- Let us now prepare the installation, picking a destination folder and editing our ``Dockerfile``: .. code:: shell PS > cd D:/ PS > mkdir install-geosx-docker PS > cd install-geosx-docker/ PS > notepad.exe Dockerfile Let us edit the ``Dockerfile``, which is the declarative file for out container: .. literalinclude:: Dockerfile-remote-dev.example :linenos: This file enriches a base image already containing the GEOS's TPL as well as extra utils, such as ``cmake`` and preparing for ssh connexion. In the end, we will be able to run it in a detached mode, and connect to it to run and develop in GEOS. There are two things you may have noticed reading through the ``Dockerfile`` : - It has environment variables to be passed to it to select the proper image to pull, namely ``${ORG}``, ``${IMG}`` and ``${VERSION}``, we'll then have to declare them .. code:: shell PS> $env:VERSION='224-965' PS> $env:IMG='ubuntu20.04-gcc9' PS> $env:REMOTE_DEV_IMG="remote-dev-${env:IMG}" Please note the preposition of ``env:`` in the windows formalisme. The ``${ORG}`` variable will be hard-coded as ``geosx``. The last variable will be use as the image name. ``224-965`` refers to a specific version of the TPLs which may not be up to date. Please refer to :ref:`Continuous_Integration_process` for further info. - You'll need to generate a ssh-key to be able to access the container without the need for defining a password. This can be done from the *PowerShell*, .. code:: shell PS > ssh-keygen.exe PS > cat [path-to-gen-key]/[your-key].pub The first command will prompt you with a message asking you to complete the desired path for the key as well as a passphrase, with confirmation. More details on `ssh-key generation `_. 4. Build the image and run the container ----------------------------------------- The preliminary tasks are now done. Let us build the image that will be containerized. .. code:: shell PS> cd [path-to-dockerfile-folder]/ PS > docker build --build-arg ORG=geosx --build-arg IMG=${env:IMG} --build-arg VERSION=${env:VERSION} -t ${env:REMOTE_DEV_IMG}:${env:VERSION} -f Dockerfile . As described above, we are passing our environment variables in the building stage, which offer the flexibility of changing the version or image by a simple redefinition. A log updating or pulling the different layers should be displayed afterwards and on the last line the *image id*. We can check that the image is created using ``PowerShell`` CLI: .. code:: shell PS > docker images or using the *Docker Desktop* .. image:: win_install/win_docker_images.png :width: 45% Now that we have the image build, let us run a container from, .. code:: shell PS > docker run --cap-add=SYS_PTRACE -d --name ${env:REMOTE_DEV_IMG}-${env:VERSION} -p 64000:22 --mount 'type=bind,source=D:/install_geosx_docker/,target=/app' ${env:REMOTE_DEV_IMG}:${env:VERSION} Note that in addition to the detached flag (``-d``) and the name tage (``--name``), we provide ``Docker`` with the port the container should be associated to communicate with ssh port 22, as well as a binding between a host mount point (``D:/install_geosx_docker/``) and a container mount point (``/app``) to have a peristent storage for our development/geosx builds. More details on the `--mount options `_ A similar step can be achieved using the *Docker Desktop* GUI in the image tabs, clicking on the *run* button and filling the same information in the interface, .. image:: win_install/win_docker_container.png :width: 45% Coming back to our ``PowerShell`` terminal, we can check that our container is running and trying to ssh to it. .. code:: shell PS > docker ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 1efffac66c4c remote-dev-ubuntu20.04-gcc9:224-965 "/usr/sbin/sshd -D" Less than a second ago Up 18 seconds 0.0.0.0:64000->22/tcp, :::64000->22/tcp remote-dev-ubuntu20.04-gcc9-224-965 PS > ssh root@localhost -p 64000 Enter passphrase for key 'C:\***********/.ssh/id_rsa': Welcome to Ubuntu 18.04.5 LTS (GNU/Linux 5.10.16.3-microsoft-standard-WSL2 x86_64) * Documentation: https://help.ubuntu.com * Management: https://landscape.canonical.com * Support: https://ubuntu.com/advantage This system has been minimized by removing packages and contents that are not required on a system that users do not log into. To restore this content, you can run the 'unminimize' command. The programs included with the Ubuntu system are free software; the exact distribution terms for each program are described in the individual files in /usr/share/doc/*/copyright. Ubuntu comes with ABSOLUTELY NO WARRANTY, to the extent permitted by applicable law. root@b105f9ead860:~# cd /app && ls We are now logged into our container and can start :ref:`QuickStart`. .. note:: Note that : #. You might be prompted that you miss certificates to clone, this can be resolved by installing *ca-certificates* and updating them #. It might occur that *git-lfs* is missing then install it .. code:: shell PS > apt install ca-certificates && update-ca-certificates PS > apt install git-lfs From there you should be able to develop in your container or access it from an IDE, e.g. `VSCode `_ or `MSVC19 `_. 5. Running a case ------------------- Once the code is configured and compiled, let us check the status of the build, .. code:: shell root@b105f9ead860:~# cd [path-to-build]/ && ./bin/geosx --help Trying to launch a case using ``mpirun``, you might get the following warning .. code:: console root@b105f9ead860:/tmp# mpirun -np 4 /app/code/GEOS/build-environment-debug/bin/geosx -i [geosx-case].xml -x 4 -y1 -z1 -------------------------------------------------------------------------- mpirun has detected an attempt to run as root. Running at root is *strongly* discouraged as any mistake (e.g., in defining TMPDIR) or bug can result in catastrophic damage to the OS file system, leaving your system in an unusable state. You can override this protection by adding the --allow-run-as-root option to your cmd line. However, we reiterate our strong advice against doing so - please do so at your own risk. -------------------------------------------------------------------------- A possible workaround is to create a new user account and a run folder from this account .. code:: shell root@b105f9ead860:~# adduser runner root@b105f9ead860:~# su runner runner@b105f9ead860:/root$ mkdir -p /tmp/geosx && cd /tmp/geosx/ runner@b105f9ead860:/tmp/geosx$ cp [path-to-case]/[geosx-case].xml . runner@b105f9ead860:/tmp/geosx$ ${MPIEXEC} -np 4 /app/code/GEOS/build-environment-debug/bin/geosx -i [geosx-case].xml -x 4 -y 1 -z 1 .. GPU ?? https://docs.docker.com/desktop/windows/wsl/#gpu-support