Docker Set up

Windows 10 or Greater

Set-up

The following will need to be pre-installed:

• Windows Subsystem for Linux WSL
• Docker Desktop. You will likely need to make a Docker account
• VcXsrv Windows X Server. This is the X11 window server. Make sure to check 'Fonts' at install. If only the command line interface is going to be used installation of this can be skipped

Quick Start

1. Download the Dockerfile from the ESP-r repository
2. Open Powershell and navigate to the directory where Dockerfile was saved
3. Issue the following command: docker build -t espr .(The period at the end needs to be there). This will create an image of an Ubuntu OS with all dependencies needed to compile and run ESP-r
4. Once the image is done building use the following command to create a new virtual environment from the image you just created: docker run -it espr /bin/bash. In Docker parlance this virtual environment is called a "container", and is built from the "image" which is essentially a template of a system configuration.
5. You now have terminal access to the virtual machine. Go to the home directory (cd home) and clone a copy of the ESP-r source code: git clone https://github.com/ESP-rCommunity/ESP-rSource
6. Navigate into the cloned repository (cd ESP-rSource) and use the following commands to compile the command-line interface version of ESP-r:
   • chmod u+x Install (This gives you permission to execute the Install bash script)
   • ./Install -d /usr/esru/devel/ --no_training --noX --gcc4 --silent
7. Once compiling is complete test that the install has worked: /usr/esru/devel/bin/prj
8. To exit out of the container simply type exit
9. To re-access the container there are a couple steps. First we need the "name" of the container. You can either retrieve this from the Docker Desktop application or the command line. From Powershell type docker container ls -a. This will list all the containers currently on your local machine along with their statuses, what image they were built from, their names and IDs. Copy the container ID of the container you want to access. It the status is listed as Exited it'll have to be restarted using the following command: docker restart <CONTAINER_ID>. Once it's restarted use the command to access the terminal into the container: docker exec -it <CONTAINER_ID> /bin/bash

Running the Graphical Interface

To use the graphical interface VcXsrv Windows X Server needs to be installed and running prior accessing the container. Start the server on the Windows host machine using XLaunch and select the following options:

1. Select "Multiple Windows" and set "Display Number" to "-1". Click "Next".
2. Select "Start no client" then "Next".
3. Make sure all boxes are checked including "Disable access control" then click "Next" and then "Finish".

Start a new container or re-connect to an existing one. Then use the following steps:

1. Open "CMD" on Windows and run the command ipconfig.
2. Copy the IPv4 Address. There may be a few so you have have to try them all until it works.
3. In the container command line type export DISPLAY=<IP_ADDRESS>:0.0 where <IP_ADDRESS> is the IPv4 Address from step 3.
4. Try launching prj.
   • You will need to have compiled ESP-r with the X11 libraries first. One way is ./Install -d /usr/esru/devel/ --xml --no_training --gcc4 --silent
   • prj can then be launched by /usr/esru/devel/bin/prj
5. If it doesn't work try a different IP address and run the command in Step 3 again.
6. To avoid having to run the export command every time it can be added to the .bashrc file:
   • Run the command nano ~/.bashrc
   • Somewhere near the bottom of the file add the line export DISPLAY=<IP_ADDRESS>:0.0
   • Save and close the file
   • Run source ~/.bashrc

Mapping Local Folder to Container

Mapping a folder on the host machine is a convenient way to transfer files between the host and container. The mapping is done at the time of container creation: docker run -ti -v <host_dir>:/locals espr /bin/bash where <host_dir> is the local directory. The folder /locals will be created in the container and map to the <host_dir>.