Set Up ESP with Docker

Latest review: 2026-08-21

Docker status: these builds use legacy base distributions and are currently very out of date. Updated builds are planned. Until then, use them only to reproduce older ESP material in an appropriately isolated development environment, not as the recommended environment for current ESP. Historical host-networking and X-server commands reduce isolation; use them only on a trusted network and revoke temporary display access when finished.

This guide documents the historical ESP Docker environment. For current ESP prerequisites, see the setup guide.

Table of Contents

Install Docker

If you haven’t already, install Docker by following the instructions for your OS: docs.docker.com/engine/install.

To start the Docker daemon on Linux systems you need to run:

sudo systemctl start docker


On Linux systems you will need to use sudo to run all docker commands (sudo docker) unless you add your user to the docker group. To add your user to the docker group run the following:

Security note: membership in the docker group grants root-equivalent access on a typical Linux host. Use it only on a trusted development machine; otherwise continue invoking individual Docker commands with sudo or use a rootless Docker configuration.

sudo usermod -aG docker ${USER}


Then log out and back in. You can verify you are part of the docker group by running groups.

Back to top

Docker Images

The ESP Docker images are available on Dockerhub: hub.docker.com/repository/docker/columbiasld/esp.

The repository containing the Dockerfiles for generating the ESP Docker images are available on GitHub: github.com/sld-columbia/esp-docker.

The ESP Docker images contain:

  • the installation of all the software packages required by ESP;

  • the installation of utilities like vim, emacs, tmux, socat and minicom, useful when working with ESP;

  • an environment variables setup script to be customized with the correct CAD tools paths and licenses;

  • the ESP repository and all its submodules;

  • the installation of the software toolchains for RISC-V and SPARC.

There are four types of images, which are identified by the centos7-full, centos7-small, ubuntu18-full, and ubuntu18-small strings in the tag.

The complete images are labeled with full and they are over 8GB in size in the compressed format. We also offer smaller images labeled with small that are approximately 1GB in size, because they do not include the installation of the RISC-V and SPARC software toolchains.

These ESP Docker images were tested on Windows 10, macOS 10.15, CentOS 7, Ubuntu 18.04, and Red Hat Enterprise Linux 7.8. Host compatibility outside those historical test environments has not been validated here.

Download the ESP Docker Images

Download the Docker image by running the following command (on Windows 10 you should run it in the PowerShell). Replace <tag> with centos7-full or ubuntu18-full for the full image and with centos7-small or ubuntu18-small for the small image.

docker pull columbiasld/esp:<tag>


You may need to add login credentials to be able to pull from Dockerhub. In that case you can add your credentials by running the following. A prompt will ask for your password as well.

docker login -u <your-dockerhub-username>


Back to top

Start the Docker container

Linux

On Linux you can start a Docker container in interactive mode as follows. The security-opt, network, env and volume arguments are needed to connect the container to the host machine display, so that it’s possible to open graphical interfaces from inside the container.

docker run -it \
  --user espuser \
  --security-opt label=type:container_runtime_t \
  --network=host \
  -e DISPLAY=$DISPLAY \
  -v "$HOME/.Xauthority:/root/.Xauthority:rw" \
  columbiasld/esp:<tag> /bin/bash

If you want to login as a root user, start the container without --user espuser argument. If you want to mount a folder from the local machine, use the volume argument. For example, if you want to use CAD tools on your local machine and the CAD tools are in the /opt folder, add -v "/opt:/opt" to the above command. See “CAD tools with Docker” section below.

macOS

On macOS you need to make sure that the X server is running and is configured properly to be able to open graphical interfaces from inside the Docker container:

  • Install XQuartz

  • Open a terminal and launch the application with open -a XQuartz.

  • From the XQuartz drop-down menu, open Preferences.. and select the Security tab. Make sure that the check box “Allow connections from network clients” is enabled, as shown in the picture below.

XQuartz security settings

  • From the same drop-down menu, quit XQuartz. The application must exit completely, then you should restart XQuartz.

  • From a new terminal window, enable X forwarding for your current IP address. This grants that host address access to XQuartz; keep the exception active only while using the container:

      ip=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}')
  xhost + $ip


Finally, you can run the container as follows.

docker run -it \
  --network=host \
  -e DISPLAY=$ip:0 \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  columbiasld/esp:<tag> /bin/bash

When you finish, revoke the XQuartz host exception with xhost - $ip and disable “Allow connections from network clients” if you do not otherwise need it.

Windows 10

On Windows 10 you can start a Docker container in interactive mode from the Docker dashboard GUI by clicking first on the RUN button next to the Docker image name and then on the CLI button next to the running container.

To be able to launch graphical interfaces from inside the container on Windows 10 you need a couple of extra steps (adapted from these guides: guide1, guide2):

  • Install VcXsrv Windows X Server and after that launch XLaunch. In the XLaunch configuration steps use all the default configurations apart from selecting the “Disable access control” option, which is not selected by default.

    Security warning: disabling X-server access control exposes the display to other reachable clients. Use this historical configuration only on an isolated, trusted network with host firewall restrictions, and stop VcXsrv as soon as the container session ends. Do not use it on a public or otherwise untrusted network.

  • Find the IP of your Windows machine by running ipconfig in the PowerShell. Look for the IPv4 Address entry.

  • Run export DISPLAY=<host-ip-address>:0.0 in the Docker container that you previously started with the CLI button.

Test X forwarding

From inside the container you can test the connection to the host display by running xeyes or xclock.

Back to top

CAD tools with Docker

The CAD tools section has the complete list of CAD tools required by ESP. The Docker image doesn’t contain any of those CAD tools. Hence, next we describe a few options to work with CAD tools in the Docker container.

Install the CAD tools on your host machine from inside the container

Installing the CAD tools from inside the Docker container is convenient because all required packages are already installed. Moreover, this strategy is especially useful if your host machine doesn’t run CentOS 7, which is the OS running in the Docker container. However, instead of installing the CAD tools inside the container, it’s preferable to install them on the host machine, so that they can be used also by other containers or even natively on the host machine in some case. In addition, it’s better to avoid committing to the Docker image the large CAD tools installation folders.

Installing the CAD tools on the host machine from inside the container can be done by using volumes or bind mounts, which are the two main ways for persisting data generated by and/or used by Docker containers. Use bind mounts if you want to specify the absolute path on the host machine where the CAD tools should be. Use volumes if you want the data to live inside Docker’s storage directory, which is managed by Docker (this is preferable on Windows and macOS).

You can declare multiple volumes and bind mounts when you launch the container with docker run by adding the following arguments.

  • Volume: -v <volume-name>:/cad-tools-path/inside/container. The volume called <volume-name> lives inside the Docker’s storage directory and it will be accessible from inside the container at the path /cad-tools-path/inside/container.

  • Bind mount: -v /cad-tools-path/on/host:/cad-tools-path/inside/container. The file or folder /cad-tools-path/on/host will be accessible from inside the container at the path /cad-tools-path/inside/container.

The idea is that from inside the container you can install the CAD tools at the path(s) of the volumes or bind mounts that you defined. Once the tools are installed, every container can access them if it receives the proper volume or bind mount arguments.

Use CAD tools already installed on your host machine

This option is useful if you already have some of the CAD tools installed on your host machine and if the host machine OS matches the one of the Docker container. In that case you can simply give access to the CAD tools with a bind mount when you start a container, by passing the -v argument as decribed in the previous section: -v /cad-tools-path/on/host:/cad-tools-path/inside/container.

Install the CAD tools inside the container

If you want a fully self-contained container, you can install the tools directly inside the container, without defining any volumes or bind mounts. The issue with this solution is that the container size will increase considerably, making it less portable.

Environment variables with Docker

The ESP Docker image provides two scripts for setting the required environment variables, as specified in the environment variables section.

Source the esp_env.sh script if you don’t need to use any CAD tools.

cd /home/espuser
source esp_env.sh


If you need some CAD tools you can use the esp_env_cad.sh instead. You should customize the script by inserting the paths of your tools and licences and by commenting out the environment variables for the tools that you don’t have. Then you should source the script.

cd /home/espuser
source esp_env_cad.sh


Back to top

Useful Docker commands

Exit a container:

# run from inside the container
exit


List all local containers and their IDs:

docker ps -a


Stop a container:

docker stop <container-ID>


Start a container:

docker start <container-ID>


Attach to a running container:

docker attach <container-ID>


Copy data from host machine to a container:

docker cp <path-on-host> <container-ID>:/<path-inside-container>


Delete a container:

docker rm -f <container-ID>


List all local images:

docker images


Delete an image:

docker rmi <image-name>


Here is the complete Docker documentation.

Back to top