docker-quickstart.txt

1. If your host machine is MacOS or Windows,
    install Docker Desktop from the Docker website: https://docs.docker.com/install/ .
    If you are already using a linux machine, install a Docker Server.
    Note if you are running Docker Toolbox (some older OSes can only support Docker Toolbox), we will not be supporting you.
    In that case we recommend you first upgrade your OS and then try Docker Desktop installation again.

2. At this point you have Docker Desktop or Docker Server installed on your host machine.
    Navigate to your CS165 project root. When you run `ls` you should be able to see a file named `dockerfile`.
    In short, the dockerfile tells docker how to prepare and build an image that is required for this project.
    We will use a `cs165` image that runs Ubuntu 18.04.
    Generally, it is not required of you to modify the dockerfile, unless:
    A) you introduce any new linux dependencies for development purposes (e.g. vim/emacs, lint or syntax tools, or other packages you would get from apt-get)
    B) you add new scripts that you want to trigger when a Docker Container is started from your image.
    Docker's reference on dockerfile syntax available here: https://docs.docker.com/engine/reference/builder/

3. Run `docker build -t cs165 .` . We have also made a convenience command in the project root Makefile that also does this `make build`.
    Take the time to understandThis command triggers Docker to build the cs165 image from the dockerfile in the current directory,
    and tags it with the name `cs165`.
    From here on, note that you will need to rerun this command anytime after you change your dockerfile,
    to persist those new changes to your local image (otherwise you will still be running off your old local image).

    Now you can confirm this image has been created/updated, by running: `docker image list`.
    This will show images, by their (repository) name, version tags, Image ID and last modified/cretaed,
    as well as disk space occupied on the host system.

    Note that for advanced use, during the `docker build` step is when you can specify other hardware resource usage constraints
    on the image (memory limits, cpu sharing, etc).
    You may read more on the advanced options here: https://docs.docker.com/engine/reference/commandline/build/

4. To start a container in interactive mode (a container will be spun out of the cs165 image, and execute and leave off in interactive shell mode,
where you can then go do your things interactively with the cmd line), you can run `docker container run` with options,
which we also wrap in a convenience command in the project root Makefile in `make run`.
`make run` is configured to do a 2-way read/write b/t your docker container and your host file system,
by binding your host `src` and `project_tests` folders into the host file system inside your container at /cs165/...
Note that this bind mount, allows your dockerfile to modify these two project subfolders on your host file system.
This means you can choose to develop your project inside the Docker container itself (e.g. edit your code directly with vim/emacs etc)
or you can also use your host system editor/IDE, and simply run/enter the container to do your builds and tests.
We leave your preferred workflow up to your discretion, these are merely two common approaches you can take.

Note that you can customize the `docker container run` options to
also specify hardware resources available to your container and other advanced options.
More on how to do that here: https://docs.docker.com/engine/reference/commandline/container_run/

You can customize the project root Makefile, by adding your own new targets (e.g. for your own testing).
You can do this at the bottom of the file marked for customization.
Do not change the ones needed for automated testing which we have labeled. That will be how we grade you.

5. Stopping containers and maintaining your Docker space usage.
You may notice that containers can hang around if not specified with the --rm option when they are run.
These take up space on your hard disk!
You can periodically use the `docker system prune` command to cleanup stopped containers and dangling images.
Note you can only prune stopped containers. You can find these by running `docker container list`.
You can use the `docker container kill <CONTAINERID>` command to stop a specific container.
For more details on related commands see this resource: https://linuxize.com/post/how-to-remove-docker-images-containers-volumes-and-networks/

6. Important Subnotes for Varied Host OS Users:

    The following sub-note is for Windows 10 Linux Subsystem Users (WSL) only:
    We recommend you consult the protocol in this article:
    https://nickjanetakis.com/blog/setting-up-docker-for-windows-and-wsl-to-work-flawlessly .
    In short, you can easily run our build system in the Windows 10 WSL (in say, an Ubuntu environment) while
    running Docker containers in windows. This happens by using an unencrypted TCP connection between the WSL
    and your Windows Docker. Note that this is a 'hacky' workaround, and is insecure if you are connected to unencrypted/public wifi
    (at worst, adversaries could potentially give commands to your Windows Docker to run arbitrarily).
    Therefore, we recommend you enable the "Expose daemon on tcp://localhost:2375 without TLS" option with caution.
    Turn it off when you don't need it for testing.

    The following sub-note is for Mac and some Windows users:
    Intel Macs support a different practice for reporting for some intra-cpu hardware performance counters,
    such as CPU branch mis-predictions.
    For these counters, perf stats will likely report "<not supported>", this is to be expected.

    If you are running Docker inside a VM host yourself on top of your Host OS, you will likely also encounter
    similar lack of reporting for certain intra-cpu hardware performance counters. This is to be expected.