Migrated Docker ORFS quickstart guide from Google Doc to MD

fixed typo

Signed-off-by: Jeff Ng <[email protected]>

Author: jeffng-or

docs/tutorials/DockerORPackageQuickstart.md

@@ -0,0 +1,190 @@
+# OpenROAD Docker Software Package Quickstart Guide
+
+# Setup Guide
+
+This setup guide covers machine and software package installation instructions for use with the OpenROAD and OpenROAD Autotuner products. It is intended to be a reference for those setting up a machine to run OpenROAD on.
+
+# Host Machine Requirements
+
+We suggest running a Ubuntu 22.04 or Red Hat Enterprise Linux 8 image with at least 32 CPUs, 128 GB memory, and 500 GB disk.
+
+# Software Packages
+
+The following are software packages that need to be installed to run OpenROAD or OpenROAD Autotuner using docker.
+
+## Docker Installation
+
+We will use Docker to create and run an image that contains everything you need to run the OpenROAD flow. If you already have Docker installed on your cloud machine, you can skip this step.
+
+### Ubuntu Installation
+
+To install Docker:
+
+```
+sudo snap install docker  
+sudo groupadd docker
+```
+
+The docker group needs to be created in order to access the pipe used by docker.
+
+### Red Hat Enterprise Linux Installation
+
+To install Docker:
+
+```
+sudo dnf install dnf-plugins-core -y  
+sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
+sudo dnf install --allowerasing -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin sudo systemctl start docker
+```
+
+The RHEL docker installation automatically adds the docker group to the system, so you can skip the next step.
+
+### Adding the Docker Group to your User
+
+Add the docker group to your user to it, so that you have access to the docker pipe:
+
+```
+sudo usermod -aG docker $USER
+```
+
+Note that you might either need to log out/log back in or reboot in order for the group change to take effect.
+
+To test that docker is working:
+
+```
+docker run hello-world
+```
+
+## Podman-Docker Installation
+Note: These instructions might only be applicable to RHEL only
+
+Alternatively, you can install podman instead of docker. On RHEL systems, podman might already be installed. To emulate the docker CLI using podman, install the podman-docker package:
+
+```
+sudo yum install podman-docker
+```
+
+To quiet the docker compatibility message:
+
+```
+sudo touch /etc/containers/nodocker
+```
+
+## VNC Installation
+
+If you are interested in using the OpenROAD GUI to track the run or view the results, you’ll need to install VNC on the cloud machine. If you have these already installed on the host machine, you can skip this step.
+
+### Ubuntu Installation
+
+To install:
+
+```
+sudo apt update  
+sudo apt upgrade -y  
+sudo apt install tigervnc-standalone-server tigervnc-xorg-extension tigervnc-viewer -y  
+sudo apt install xfce4-goodies xfce4 -y
+```
+
+Start a vncserver session on the cloud machine and connect the VNC client to it.
+
+### Red Hat Enterprise Linux Installation
+
+To install:
+
+```
+sudo dnf update -y  
+sudo dnf install tigervnc-server tigervnc-server-module -y  
+sudo dnf groupinstall "Server with GUI" -y
+```
+
+Start a vncserver session on the cloud machine and connect the VNC client to it.
+
+## XHost Access
+
+In order for the docker container to display the GUI, you must enable docker containers access to the X11 display on the cloud machine. To enable access:
+
+```
+xhost +local:docker  
+touch /tmp/.docker.xauth
+```
+
+## Git Installation
+Note: These instructions are applicable to RHEL only
+
+To install git:
+
+```
+sudo dnf install git-core -y
+```
+
+## Firefox Installation
+Note: These instructions are applicable to Ubuntu only
+
+Firefox (or your favorite browser) enables you to view the OpenROAD AutoTuner results via TensorBoard. If you have already installed firefox on the cloud machine, you can skip this step.
+
+To install firefox:
+
+```
+sudo snap install firefox
+```
+
+## TensorBoard Installation
+
+### Ubuntu Installation
+
+If you want to run TensorBoard on the cloud machine, type the following to install it:
+
+```
+sudo apt install python3-pip -y  
+sudo pip install tensorboard
+```
+
+### Red Hat Enterprise Linux Installation
+
+If you want to run TensorBoard on the cloud machine, type the following to install it:
+
+```
+sudo dnf install python3-pip -y  
+sudo dnf install redhat-rpm-config -y  
+sudo dnf install python3-devel  
+sudo dnf groupinstall “Development Tools” -y  
+sudo pip3 install tensorboard
+```
+
+# Choosing The ORFS Version
+
+The OpenROAD team frequently releases new versions of ORFS and publishes them on [Docker Hub](https://hub.docker.com/r/openroad/orfs/tags)). Based upon your needs, you can choose which version to use in your flow. 
+
+Each version has a listing, which includes the ORFS tag:
+
+![](images/orfs_dockerhub_tag.png)
+
+In our example above, the tag is v3.0-2144-gd8465608, where 2144 is the build number and gd8465608 is a hash that is related to the corresponding commit tag in the Git OpenROAD-flow-scripts repository.
+
+## Locating the Commit in the OpenROAD-flow-scripts Repository
+
+Locating the commit in the OpenROAD-flow-scripts repository is important in this flow to ensure that the ORFS scripts and the ORFS tools are aligned. It can also be helpful in case you require a specific feature or fix in your flow.
+
+The ORFS Git commit tag version is similar to the Docker Hub tag, but might not be exact. Generally-speaking the Docker Hub tag is the ORFS Git commit tag with a “g” prepended to it and possibly another digit at the end. For the example below, the ORFS Git commit tag is d846560 and the Docker Hub tag is gd8465608.
+
+Please consult the [ORFS git history](https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts/commits/master/) to find the commit tag that most closely matches the Docker version tag. The commit tag is listed on the right side of each commit (d846560):
+
+![](images/orfs_git_commit.png)
+
+# Workspace Creation
+
+We want to store all of our design’s artifacts on the cloud machine’s filesystem, so that all OpenROAD tool invocations can use the same artifacts.
+
+## Clone the ORFS Flow Directory
+
+The easiest way to create the workspace is to clone out the OpenROAD-flow-scripts repository from git onto our host machine and then share it with Docker. In order to ensure that there’s compatibility between the OpenROAD tool and the flow scripts, we’ll want to access the same ORFS version as what we are using in the Docker container defined in the “Locating the Commit in the OpenROAD-flow-scripts Repository” section above (e.g. version d846560)
+
+To clone the repository:
+
+```
+git clone --recursive https://github.com/The-OpenROAD-Project/OpenROAD-flow-scripts.git
+cd OpenROAD-flow-scripts  
+git checkout d846560
+```
+
+Note that if we change the version of the ORFS tools we are using, we will also need to run “git pull” followed by a “git checkout” with the corresponding Git commit tag.

docs/tutorials/DockerORQuickstart.md

@@ -0,0 +1,79 @@
+# OpenROAD Docker Quickstart Guide
+
+# Setup Guide
+
+The easiest method for running the OpenROAD flow scripts (ORFS) on a cloud machine is through a Docker container, which doesn’t require any code compilation. We suggest running a Ubuntu 22.04 or Red Hat Enterprise Linux 8 image with at least 32 CPUs, 128 GB memory, and 500 GB disk.
+
+The cloud machine serves three purposes:
+
+1. Hosts the Docker container  
+2. Hosts the persistent filesystem for the results of your OpenROAD runs  
+3. Enables you to view the OpenROAD results through the OpenROAD GUI
+
+# Host Machine Setup Requirements
+
+Running the OpenROAD flow a Docker container requires a few software packages to be installed on the cloud machine:
+
+- [Docker (or Podman)](DockerORPackageQuickstart.md#docker-installation)
+- [Podman-docker](DockerORPackageQuickstart.md#podman-docker-installation) (if using Podman)  
+- [VNC](DockerORPackageQuickstart.md#vnc-installation)  
+- [XHost access](DockerORPackageQuickstart.md#xhost-access)  
+- [Git](DockerORPackageQuickstart.md#git-installation) (RHEL only)
+
+If these packages are already installed on your cloud machine, you are ready to run ORFS. Otherwise, please follow the instructions in the links above to install the packages.
+
+# Choosing The ORFS Version
+
+See the [Choosing The ORFS Version](DockerORPackageQuickstart.md#choosing-the-orfs-version) section for instructions on how to choose an ORFS version and create your workspace.
+
+# OpenROAD Execution
+
+## Using Docker Shell
+
+The ORFS tools provide a utility called docker\_shell, which can be used to execute commands within a Docker container. The script is located in flow/utils/docker\_shell under the ORFS root directory.
+
+To execute our Docker container as a shell, we can run the following command on our cloud machine:
+
+```
+cd flow  
+export OR_IMAGE=openroad/orfs:v3.0-2144-gd8465608  
+util/docker_shell <shell_command>
+```
+
+We use the OR\_IMAGE environment variable to tell docker\_shell which version of ORFS we want to run. Then we can run docker\_shell with the shell command we want to execute within the container, which allows us to run the ORFS flow just like if it was installed on your cloud machine.
+
+Note that on RHEL, you might need to include the location of the docker repository in the OR\_IMAGE environment variable:
+
+```
+export OR_IMAGE=docker.io/openroad/orfs:v3.0-2144-gd8465608
+```
+
+## Running OpenROAD
+
+The ORFS flow leverages “make” to define the flow variables that control the flow and manages the tool execution based on dependencies. To build all stages for the IBEX design on the ASAP7 platform, execute:
+
+```
+./util/docker_shell make DESIGN_CONFIG=designs/asap7/ibex/config.mk
+```
+
+All of the data is stored in the flows directory in the following sub-directories:
+
+- results: contains the ORFS generated databases and design files  
+- logs: contains the ORFS stage log files  
+- reports: contains the ORFS stage reports
+
+## Running the OpenROAD GUI
+
+To run the OpenROAD GUI to view the final stage results:
+
+```
+./util/docker_shell make DESIGN_CONFIG=designs/asap7/ibex/config.mk gui_final
+````
+
+You can explore the design hierarchy, heat maps, clock tree, and timing reports directly from within the GUI.
+
+# References
+
+OpenROAD-flow-scripts documentation: [link](https://openroad-flow-scripts.readthedocs.io/en/latest/index2.html)  
+OpenROAD-flow-scripts tutorial: [link](https://openroad-flow-scripts.readthedocs.io/en/latest/tutorials/FlowTutorial.html)  
+OpenROAD-flow-scripts GUI tutorial: [link](https://openroad-flow-scripts.readthedocs.io/en/latest/tutorials/FlowTutorial.html#openroad-gui)

docs/tutorials/TutorialHome.md

@@ -3,3 +3,5 @@
 The links to the main flow tutorial, where we go through each step of 
 the RTL-GDSII flow are as [follows](FlowTutorial.md). We have also provided
 Google Colab packaging for ease of experimentation [here](Notebooks.md).
+
+If you are interested in running OpenROAD locally, also check out the [Docker OpenROAD Quickstart Guide](DockerORQuickstart.md).