[windows] Improve documentation about the Windows backend

Author: amotl

CHANGES.rst

@@ -18,6 +18,7 @@ in progress
 - Add support for Windows Server Core 2016, 2022 and friends, like
   ``windows/servercore:ltsc2016``, ``windows/servercore:ltsc2022``, or
   ``windows/nanoserver:ltsc2022``.
+- Improve documentation about the Windows backend
 
 2022-05-20 0.2.0
 ================

README.rst

@@ -224,7 +224,9 @@ Racker
 The ``racker`` program aims to resemble the semantics of Docker by providing a
 command line interface compatible with the ``docker`` command.
 
-Linux examples::
+Linux
+-----
+::
 
     # Invoke the vanilla Docker `hello-world` image.
     # FIXME: Does not work yet.
@@ -256,47 +258,19 @@ Linux examples::
     time echo "hello world" | racker run -it --rm fedora:37 cat /dev/stdin > hello
     cat hello
 
-Windows examples::
-
-    # Windows OS images, mostly LTSC (Long-Term Servicing Channel).
-    # Please note the download sizes.
-    # Nanoserver: 250 MB, Servercore: 6 GB, Servercore with Java: 7 GB, Windows: 15 GB
-
-    # Launch an interactive command prompt (cmd, PowerShell or Bash).
-    racker --verbose run -it --rm --platform=windows/amd64 mcr.microsoft.com/windows/servercore:ltsc2016-amd64 cmd
-    racker --verbose run -it --rm --platform=windows/amd64 mcr.microsoft.com/windows/servercore:ltsc2019-amd64 powershell
-    racker --verbose run -it --rm --platform=windows/amd64 mcr.microsoft.com/windows/servercore:ltsc2022-amd64 bash
-
-    # Launch a single command.
-    racker --verbose run --rm --platform=windows/amd64 mcr.microsoft.com/windows/servercore:ltsc2019-amd64 -- 'powershell -Command {echo "Hello, world."}'
-    racker --verbose run --rm --platform=windows/amd64 mcr.microsoft.com/windows/servercore:ltsc2019-amd64 'sh -c "echo Hello, world."'
-
-    # Inquire system information.
-    racker run --rm --platform=windows/amd64 mcr.microsoft.com/windows/servercore:ltsc2019-amd64 wmic os get caption
-    racker run --rm --platform=windows/amd64 mcr.microsoft.com/windows/servercore:ltsc2019-amd64 'powershell -Command Get-ComputerInfo'
-
-    # Use stdin and stdout, with time keeping.
-    time racker --verbose run --rm --platform=windows/amd64 mcr.microsoft.com/windows/nanoserver:1809-amd64 cmd /C echo "Hello, world." > hello
-    cat hello
+Windows
+-------
 
-    # Invoke a Java command prompt (JShell) with different Java versions.
-    racker run -it --rm --platform=windows/amd64 openjdk:18-windowsservercore-1809 jshell
-    racker run -it --rm --platform=windows/amd64 openjdk:19-windowsservercore-ltsc2022 jshell
-    racker run -it --rm --platform=windows/amd64 eclipse-temurin:18-jdk jshell
-    System.out.println("OS: " + System.getProperty("os.name") + ", version " + System.getProperty("os.version"))
-    System.out.println("Java: " + System.getProperty("java.vendor") + ", version " + System.getProperty("java.version"))
-    /exit
+An example of a basic command line invocation should get you started,
+especially if you are familiar with the ``docker`` command::
 
-    # Windows Nano Server.
-    racker --verbose run -it --rm --platform=windows/amd64 mcr.microsoft.com/windows/nanoserver:1809-amd64 cmd
-    racker --verbose run --rm --platform=windows/amd64 mcr.microsoft.com/windows/nanoserver:1809-amd64 cmd /C echo Hello, world.
-    racker --verbose run --rm --platform=windows/amd64 mcr.microsoft.com/windows/nanoserver:ltsc2022-amd64 cmd /C echo Hello, world.
-    racker --verbose run -it --rm --platform=windows/amd64 mcr.microsoft.com/powershell:nanoserver-ltsc2022 pwsh
+    racker --verbose run --rm --platform=windows/amd64 mcr.microsoft.com/windows/servercore:ltsc2022 -- wmic os get caption
 
-    # Full Windows.
-    racker --verbose run -it --rm --platform=windows/amd64 mcr.microsoft.com/windows:1809-amd64 cmd
-    racker --verbose run -it --rm --platform=windows/amd64 mcr.microsoft.com/windows:ltsc2022-amd64 cmd
+    Caption
+    Microsoft Windows Server 2022 Datacenter
 
+More extensive information, including many examples, can be found at the
+`Racker Windows backend`_ documentation.
 
 
 Postroj
@@ -483,6 +457,7 @@ Troubleshooting
 .. _Packer: https://www.packer.io/
 .. _Podman: https://podman.io/
 .. _Racker sandbox installation: https://github.com/cicerops/racker/blob/main/doc/sandbox.rst
+.. _Racker Windows backend: https://github.com/cicerops/racker/blob/main/doc/winrunner.rst
 .. _skopeo: https://github.com/containers/skopeo
 .. _systemd: https://www.freedesktop.org/wiki/Software/systemd/
 .. _systemd-nspawn: https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html

doc/cratedb.rst

@@ -2,47 +2,27 @@
 Using Racker and Postroj for CrateDB CI
 #######################################
 
-.. note::
-
-    This is still a work in progress.
-
-
-*************
-Prerequisites
-*************
-
-When creating the "Windows Docker Machine" virtual machine, the program will
-configure it to use 6 VPUs and 6144 MB system memory.
-
-In order to adjust those values, use these environment variables before
-invoking the later commands::
-
-    export RACKER_VM_VCPUS=12
-    export RACKER_VM_MEMORY=8192
-
-If you want to adjust the values after the initial deployment, you will have to
-reset the "Windows Docker Machine" installation directory. For example, it is:
-
-- On Linux: ``/root/.local/state/racker/windows-docker-machine``
-- On macOS: ``/Users/amo/Library/Application Support/racker/windows-docker-machine``
-
-
 
 **********
 racker run
 **********
 
 Purpose: Invoke programs in a Java/OpenJDK environment, within a
-virtualized/dockerized Windows installation.
+virtualized/dockerized, volatile/ephemeral Windows environment.
 
 Run the CrateDB test suite on OpenJDK 18 (Eclipse Temurin)::
 
-    time racker run --rm --platform=windows/amd64 eclipse-temurin:18-jdk \
+    time racker --verbose run --rm --platform=windows/amd64 eclipse-temurin:18-jdk \
         "sh -c 'mkdir /c/src; cd /c/src; git clone https://github.com/crate/crate --depth=1; cd crate; ./gradlew --no-daemon --parallel -PtestForks=2 :server:test -Dtests.crate.run-windows-incompatible=false --stacktrace'"
 
+Use the same image, but select a specific operating system version::
+
+    export RACKER_VM_BOX=2019-box
+    racker --verbose run --rm --platform=windows/amd64 eclipse-temurin:18-jdk -- wmic os get caption
+
 Invoke a Java command prompt (JShell) with OpenJDK 18::
 
-    racker run -it --rm --platform=windows/amd64 eclipse-temurin:18-jdk jshell
+    racker --verbose run -it --rm --platform=windows/amd64 eclipse-temurin:18-jdk jshell
     System.out.println("OS: " + System.getProperty("os.name") + ", version " + System.getProperty("os.version"))
     System.out.println("Java: " + System.getProperty("java.vendor") + ", version " + System.getProperty("java.version"))