diff --git a/doc/docker.md b/doc/docker.md index c277336..b9670f7 100644 --- a/doc/docker.md +++ b/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 -beginner. +This guide is tailored toward a Debian-based machine (and tested on Debian 12). +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`, -gateway `192.168.1.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. +Set the ethernet port to static ip `192.168.2.100/24`, netmask `255.255.255.0`, +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.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: - make $NAME-copy $NAME-execute $NAME-get +```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