Improve Docker setup:

- Refuse to install Docker under WSL.
- Install tools in venv if it's activated.
- Improve docs.

Author: bjones1

docker/README.rst

@@ -8,22 +8,21 @@ Docker Deployment
     If you would prefer to install all the components directly on a server yourself,
     see the `Manual Installation instructions <../docs/installation.html>`_.
 
-
 Using Docker, we can bring up the server without needing to install dependencies directly on
 the host. Instead, the software required to run the server will be installed in four separate
-docker containers (Runestone application, redis cache, postgres DB, jobe code compilation).
-
+Docker containers (the Runestone application, redis cache, postgres DB, and Jobe code compilation).
 
 .. note::
 
     These instructions have been tested on Ubuntu 20.04 and should work on any version of Ubuntu 18.04+.
     Installation on older versions of Ubuntu or other Linux distributions may require adjustments.
-    These instructions have also been tested on OS X. For Windows, use WSL, VirtualBox, or other similar virtualization software.
+    These instructions have also been tested on OS X. For Windows, use `WSL2 <https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-10#1-overview>`_, VirtualBox, or other similar virtualization software.
+
 
+**Contents**
 
-Contents
---------
 .. contents::
+    :local:
 
 
 Setup
@@ -40,18 +39,16 @@ To build a Docker application with the server and all its dependencies, download
     curl -fsSLO https://raw.githubusercontent.com/RunestoneInteractive/RunestoneServer/master/docker/docker_tools.py
     # See what build options are available.
     python3 docker_tools.py build --help
-    # Run the build.
+    # Run the build, choosing appropriate options for your case.
     python3 docker_tools.py build <your options here>
 
-This will take a while. But once built, you will not need to rebuild the image unless you need to modify settings
-inside it. If you do need to modify a built image, you can either `shell into the built container <Shelling Inside>`_
-to make changes or rebuild the image.
+This will take a while. But once built, you will not need to rebuild the image unless you need to modify settings inside it. If you do need to modify a built image, you can either `shell into the built container <Shelling Inside>`_ to make changes or rebuild the image.
 
 When this completes, **log out then back in** (reboot if using a VM) to update your group membership. Next, ``cd RunestoneServer``.
 
 .. note::
 
-    All future commands should be run in the ``RunestoneServer`` directory unless instructions specify otherwise.
+    All future commands should be run in the ``RunestoneServer`` directory unless instructions specify otherwise. After the first **successful** invocation of ``python3 docker_tools.py build``, use the (newly-installed) ``docker-tools`` command, instead of ``python3 docker_tools.py``. For example, ``docker-tools build <your options here>``.
 
 .. note:: VirtualBox
 
@@ -90,13 +87,11 @@ Python Settings
 You also will also likely want to configure some options in the Python code. These options
 will be in the file ``models/1.py`` (which is automatically created on the first build).
 
-
 Again, if you are installing for local development/testing you should not need to modify
 any of the settings. If you are installing for production, you will want/need to modify
 some of them (so that things like sending students emails for lost passwords work).
 See comments in the file for details.
 
-
 .. warning::
 
     You will NOT want to check either ``.env`` or ``models/1.py`` into source control. The
@@ -128,45 +123,40 @@ To stop all containers use:
 
     docker-compose stop
 
-
 To restart the containers, to reload configuration files or because you have added a new book,
 do:
 
 .. code-block:: bash
 
     docker-compose restart
 
-
 Or to just restart the Runestone container (which is generally the only one that needs to be updated):
 
 .. code-block:: bash
 
     docker-compose restart runestone
 
-
 If you ever want to completely wipe the containers, stop them and then do:
 
 .. code-block:: bash
 
     docker-compose rm
 
 
-4. Install `rsmanage`
-
-The rsmanage command will run many useful commands inside the container for you.  With rsmanage you can:
+Introducing `rsmanage`
+^^^^^^^^^^^^^^^^^^^^^^
+The ``rsmanage`` command will run many useful commands inside the container for you.  With ``rsmanage`` you can:
 
 * Add a course - ``rsmanage addcourse``
 * Add a user - ``rsmanage adduser``
-* Get infromation about a course ``rsmanage courseinfo``
+* Get information about a course ``rsmanage courseinfo``
 * Build a book - ``rsmanage build --course bookname``
 * Get a database shell in the current database ``rsmanage db``
 
-And lots of other things.  Just type ``rsmanage`` for a list of things it can do.  For a list of options just type rsmanage and the subcommand you want followed by `--help`
+...and lots of other things.  Just type ``rsmanage`` for a list of things it can do.  For a list of options just type ``rsmanage`` and the subcommand you want followed by ``--help``; for example, ``rsmanage build --help``.
 
-To install rsmanage type ``pip install -e /path/to/RunestoneServer/rsmanage``
 
-
-1. Add Books
+4. Add Books
 **************************
 
 To add a book, you need to add its source code to the ``RunestoneServer/books/`` directory. For an existing
@@ -179,7 +169,6 @@ To add a book, you need to add its source code to the ``RunestoneServer/books/``
     git clone https://github.com/RunestoneInteractive/thinkcspy.git
     cd ..
 
-
 .. warning::
 
    It is important that the folder name for the book matches the ``project_name`` set in its ``pavement.py``.
@@ -188,7 +177,7 @@ To add a book, you need to add its source code to the ``RunestoneServer/books/``
    If there is a mismatch, you will want to rename the folder you cloned the code into so that it
    matches the ``project_name``.
 
-After cloning a book, you may need to add it to the database.  Most of the standard books are already there, but you can use ``rsmanage addcourse`` to add it if needed. 
+After cloning a book, you may need to add it to the database.  Most of the standard books are already there, but you can use ``rsmanage addcourse`` to add it if needed.
 You also need to rebuild after making any edits/updates to a book.
 
 .. code-block:: bash
@@ -201,7 +190,6 @@ You can also have ``rsmanage`` clone the book for you the first time you want to
 
     rsmanage build --course thinkcspy --clone https://github.com/RunestoneInteractive/thinkcspy.git
 
-
 .. note::
 
    Most Runestone books set ``master_url`` to ``get_master_url()`` in their ``pavement.py`` file. However, if the book
@@ -210,20 +198,19 @@ You can also have ``rsmanage`` clone the book for you the first time you want to
    If you are running docker on a remote host then make sure to set it to the name of the remote host.
 
 
-1. Add Courses
+5. Add Courses
 **************************
 
 To add a course based on a book, run the ``rsmanage addcourse`` script. If you run it just like
-that it will prompt you for all of the necessary details. Probably the **most important** thing 
+that it will prompt you for all of the necessary details. Probably the **most important** thing
 to point out is that if this is a new book the first time you add it you want to make sure that the
-basecourse and the course-name are the same.  If you are creating your own course but want it 
+basecourse and the course-name are the same.  If you are creating your own course but want it
 based on an existing book then make sure to use the correct base course name.
 
 .. code-block:: bash
 
     rsmanage addcourse
 
-
 It will ask for:
 
 **Course Name**: The short name to identify this course/section (do **NOT** include any spaces).  e.g. ``yourname-cs1-fall2021``
@@ -243,7 +230,8 @@ You do not have to restart the server to make use of the course.
     Some of the default books already have "default" courses with the same name as the book. If you try to create
     a course with a name like ``thinkcspy`` you will be told that the course name is the same as the book.
 
-1. Add a User
+
+6. Add a User
 **************************
 
 To add an initial instructor account to the course you have created, you can either create a new user or add
@@ -256,15 +244,13 @@ they should be made an instructor.
 
     rsmanage adduser
 
-
 Or, if you already have an account that you want to add as an instructor to the new course, you can use the
 ``rsmanage`` command to execute **addinstructor** which will prompt you for a username and course name:
 
 .. code-block:: bash
 
     rsmanage addinstructor
 
-
 Neither of these will require restarting the server.
 
 Once you have logged in as an instructor, you can bulk add students through the web interface.
@@ -297,7 +283,6 @@ To re-build an image:
     # Actually run the build (add options as desired)
     docker-tools build
 
-
 To force a rebuild, make sure the containers are `stopped <4. Starting/Stopping>`_, then rerun the build
 command. The build process caches results from previous builds and should complete much more rapidly. However, the
 cache can cause issues if you modify a file that the system is checking for changes. If you need to force a
@@ -319,7 +304,6 @@ the RunestoneServer directory do:
 
     docker-tools shell
 
-
 Remember that the folder under web2py applications/runestone is bound to your host,
 so **do not edit files from inside the container** otherwise they will have a change
 in permissions on the host.
@@ -399,10 +383,10 @@ If you are writing your own book you will want to get that book set up properly
 system. You need to do the following:
 
 1. Run the command ``rsmanage addcourse`` Use the project name you configured in ``pavement.py`` as
-the name of BOTH the course and the basecourse when it asks. 
+the name of BOTH the course and the basecourse when it asks.
 
 
-1. Now that your course is registered rebuild it using the command ``rsmanage build --course <book_name>`` command. 
+1. Now that your course is registered rebuild it using the command ``rsmanage build --course <book_name>`` command.
 
 2. If this book is a PreTeXt book you will need to navigate to the directory that contains the
 ``runestone-manifest.xml`` file and run the command:

docker/docker_tools.py

@@ -66,8 +66,7 @@
 # ---------------------------
 # Everything after this depends on Unix utilities.
 if sys.platform == "win32":
-    print("Run this program in WSL/VirtualBox/VMWare/etc.")
-    sys.exit()
+    sys.exit("Run this program in WSL/VirtualBox/VMWare/etc.")
 
 # See if we're root.
 is_root = (
@@ -111,13 +110,26 @@ def check_install_curl() -> None:
     check_install("curl --version", "curl")
 
 
+# Check if we're running in WSL -- don't install Docker if so.
+def check_in_wsl() -> None:
+    if "WSL" in Path("/proc/version").read_text():
+        sys.exit(
+            "Docker for Windows not detected while running in WSL. You must install this before proceeding."
+        )
+
+
+# Outside a venv, install locally.
+def pip_user() -> str:
+    return "" if in_venv else "--user"
+
+
 # The working directory of this script.
 wd = Path(__file__).resolve().parent
 sys.path.append(str(wd / "../tests"))
 # fmt: off
 try:
     # This unused import triggers the script download if it's not present. This only happens outside the container.
-    import ci_utils
+    import ci_utils  # noqa: F401
 except ImportError:
     assert not os.environ.get("IN_DOCKER")
     check_install_curl()
@@ -130,7 +142,7 @@ def check_install_curl() -> None:
         ],
         check=True,
     )
-from ci_utils import chdir, env, is_darwin, is_linux, pushd, xqt
+from ci_utils import chdir, env, is_darwin, pushd, xqt  # noqa: E402
 # fmt: on
 
 # Third-party bootstrap
@@ -150,8 +162,8 @@ def check_install_curl() -> None:
     # Outside a venv, install locally.
     user = " " if in_venv else "--user "
     xqt(
-        f"{sys.executable} -m pip install {user}--upgrade pip",
-        f"{sys.executable} -m pip install {user}--upgrade click",
+        f"{sys.executable} -m pip install {pip_user()} --upgrade pip",
+        f"{sys.executable} -m pip install {pip_user()} --upgrade click",
     )
     # If pip is upgraded, it won't find click. `Re-load sys.path <https://stackoverflow.com/a/25384923/16038919>`_ to fix this.
     reload(site)
@@ -360,6 +372,7 @@ def _build_phase_0(
     try:
         xqt("docker --version")
     except subprocess.CalledProcessError as e:
+        check_in_wsl()
         check_install_curl()
         print(f"Unable to run docker: {e} Installing Docker...")
         # Use the `convenience script <https://docs.docker.com/engine/install/ubuntu/#install-using-the-convenience-script>`_.
@@ -378,6 +391,7 @@ def _build_phase_0(
     try:
         xqt("docker-compose --version")
     except subprocess.CalledProcessError as e:
+        check_in_wsl()
         print(f"Unable to run docker-compose: {e} Installing...")
         # This is from the `docker-compose install instructions <https://docs.docker.com/compose/install/#install-compose-on-linux-systems>`_.
         xqt(
@@ -395,7 +409,7 @@ def _build_phase_0(
     if clone_all != "RunestoneInteractive":
         # Print Warning and provide countdown to abort script
         click.secho(
-            "Warning: Clone-all flag was initalized and will override any other clone flag specified!",
+            "Warning: Clone-all flag was initialized and will override any other clone flag specified!",
             fg="red",
         )
         # Set each individual flag to the clone-all argument
@@ -555,19 +569,19 @@ def _build_phase_0(
         did_group_add = True
         docker_sudo = True
 
-    # Provide server-related CLIs.
+    # Provide server-related CLIs. While installing this sooner would be great, we can't assume that the prereqs (the downloaded repo) are available.
     check_install(f"{sys.executable} -m pip --version", "python3-pip")
     xqt(
-        f"{sys.executable} -m pip install --user -e docker",
-        f"{sys.executable} -m pip install --user -e rsmanage",
+        f"{sys.executable} -m pip install {pip_user()} -e docker",
+        f"{sys.executable} -m pip install {pip_user()} -e rsmanage",
     )
 
     # Run the Docker build.
     xqt(
         f'ENABLE_BUILDKIT=1{" sudo" if docker_sudo else ""} docker build -t runestone/server . --build-arg DOCKER_BUILD_ARGS="{" ".join(sys.argv[1:])}" --progress plain {" ".join(passthrough)}'
     )
 
-    # Print thesse messages last; otherwise, it will be lost in all the build noise.
+    # Print these messages last; otherwise, it will be lost in all the build noise.
     if change_dir:
         print(
             "\n"