Docker-Image.md

@@ -5,6 +5,12 @@ firesim:
   version: v1.16.0
   url: https://github.com/firesim/firesim/tree/1.16.0
   docs-url: https://docs.fires.im/en/stable/Building-a-FireSim-Xclbin.html
+  chipyard:
+    version: v1.19.0
+    url: https://github.com/ucb-bar/chipyard/tree/1.9.0
+  firemarshal:
+    version: 12784a4
+    url: https://github.com/firesim/FireMarshal/tree/12784a42cb1b2188536ef5bfc123f800374d3177
 aro-cn: D2021-2106030006
 ---
 
@@ -16,6 +22,62 @@ This work was funded by the iARPA AGILE Program. [^1]
 
 [[_TOC_]]
 
+# Prerequisites
+
+## Installing Docker
+
+<img src="https://www.docker.com/wp-content/uploads/2022/03/vertical-logo-monochromatic.png" align="right" width="250px" alt="Alveo U250">
+
+The material in this document requires the use of [Docker](https://www.docker.com/). Either one of the following options will work:
+
+- Access to a server with Docker installed
+
+  - Make sure your user account has been added to the `docker` group
+
+Use [Docker Desktop](https://docs.docker.com/get-docker/) on your local machine
+
+> **NOTE:** If you have an Apple M1/M2 (`arm`-based CPU), builds and simulations are prohibitively slow.
+> 
+> `x86-64` processors are HIGHLY recommended.
+
+## Pulling the Docker image
+
+Docker images contain all of the files and binaries needed to run a particular task. You can think of Docker images as virtual machine snapshots. Our container registry has a collection of these images. Much like Git, these _tags_ are images that contain different files for different projects. We'll pull the `latest` tag, as shown below:
+
+```bash
+docker pull socks.lbl.gov:4567/cag/bxe
+```
+
+## Running a Docker container
+
+Once you've pulled a Docker image, you can run within a container. You can think of containers as the virtual machine that's running the image you pulled. When a container is initialized and run, it's given a unique hash and a unique string name. When you want to access the container, you refer to its unique hash/string. You can also give your container a unique name, as domonstraited below:
+
+> **NOTE:** `--privileged` is only required when using FireMarshal.
+
+- Running a Docker container interactively
+  - This runs the Docker container and attaches the console of your container
+  ```bash
+  docker run [--privileged] [--name CUSTOM_CONTAINER_NAME] -it socks.lbl.gov:4567/cag/bxe
+  ```
+
+- Running a Docker container and attaching later
+  - You can run a Docker container in the background and attach to it
+  ```bash
+  docker run [--privileged] [--name CUSTOM_CONTAINER_NAME] socks.lbl.gov:4567/cag/bxe
+  docker attach [HASHID/STRINGID/CUSTOM_CONTAINER_NAME]
+  ```
+
+### Mounting Host Directories in Docker containers
+
+You can mount directories from your host machine within your container with the following command. In this example, we want to mount `/tmp/mpoint` from our host machine to `/app` in the container.
+
+```bash
+docker run \
+    [--privileged] [--name CUSTOM_CONTAINER_NAME] \
+    -it \
+    -v /tmp/mpoint:/app \
+    socks.lbl.gov:4567/cag/bxe
+```
 
 ---