Migrated changes from the upsilon-docker repo to this repo

doc/docker.md

@@ -1,9 +1,10 @@
-Upsilon docker development environment setup.
+Upsilon docker development environment setup
 
-# Dockerfile style guide
+# Docker Guide
 
-Dockerfiles should be simple. The Dockerfiles should be readable to a
+This guide is tailored toward a Debian-based machine (and tested on Debian 12).
-beginner.
+However, because most of the build process occurs within Docker containers,
+this guide should be easily adopted to run in nearly any modern Linux environment.
 
 # Setup steps
 
@@ -27,6 +28,15 @@ Docker allows you to run programs in containers, which are isolated
 environments. Build environments can be set up automatically, and re-setup
 whenever needed.
 
+To install Docker, run:
+```bash
+sudo apt install docker.io docker-compose
+```
+
+Next, using [this guide][2], create a `docker` group and add your user to
+that group. This will allow you to run docker commands without needing to run
+them as root each time.
+
 If you have issues with docker, try adding to `~/.config/docker/daemon.json`
 
     {
@@ -36,24 +46,33 @@ If you have issues with docker, try adding to `~/.config/docker/daemon.json`
 
 ## Download and Install Python3
 
-Install `python3` and `python3-pip`.
+Install `python3-venv` (or `python3-virtualenv`) and `python3-pip`:
+```bash
+sudo apt install python3-venv python3-pip
+```
 
 ## Clone External Repositories
 
 Run `make clone`. You may need to download the upsilon repositories
 and put them in the same folder as the Makefile.
 
+Note: If `make` is not already installed, you can install it by running the following
+command:
+```bash
+sudo apt install build-essential
+```
+
 ## Setup Network
 
 Plug in your router/switch to an ethernet port on your computer. If your
 computer is usually wired to the network, you will need another ethernet
 port (a PCI card is ideal, but a USB-Ethernet port works).
 
-Set the ethernet port to static ip `192.168.1.100/24`, netmask `255.255.255.0`,
+Set the ethernet port to static ip `192.168.2.100/24`, netmask `255.255.255.0`,
-gateway `192.168.1.1`. Make sure this is not the default route. Make sure
+gateway `192.168.2.1`. Make sure this is not the default route. Make sure
-to adjust your firewall to allow traffic on the 192.168.1.0/24 range.
+to adjust your firewall to allow traffic on the `192.168.2.0/24` range.
 
-If your local network already uses the 192.168.1.0/24 range, then you must
+If your local network already uses the `192.168.2.0/24` range, then you must
 modify `upsilon/firmware/soc.py` to use different IPs. You must rebuild the
 SoC after doing this.
 
@@ -70,13 +89,17 @@ For `NAME` in `hardware`, `opensbi`, `buildroot`:
 2. If the container already exists, do `docker container start upsilon-$NAME`.
 3. Run `make $NAME-copy` to copy Upsilon's code into the container.
 4. Run `make $NAME-execute` to build the data.
-5. Run `make $NAME-get` to retrieve the build artefacts.
+5. Run `make $NAME-get` to retrieve the build artifacts.
 
-If you do not delete the container you can run
+If you do not delete the container you can run the following when you need to rebuild:
 
+```bash
 make $NAME-copy $NAME-execute $NAME-get
+```
 
-when you need to rebuild. If you need shell access, run `make $NAME-shell`.
+If you need shell access, run `make $NAME-shell`.
+
+Run `make $NAME-clean` to delete the container.
 
 ## Launch TFTP Server