Troubleshooting

Insufficient Memory

Problem:

DeGAUSS seems to run without reporting any errors, but does not produce an output file. Intermediate directories (Rtmp..., cache, degauss_cache) directories are created, but the program seems to terminate prematurely.

Solution

Some of the DeGAUSS images require a large amount of system memory, or RAM, to complete the operation. If insufficient memory is available to Docker, then the DeGAUSS image will fail without notifying the user. This can be fixed by increasing the amount of RAM allocated to the virtual machine hosting Docker. This can be done using the installation wizard, the Docker control panel, or settings in VirtualBox, all depending on the version of Docker and version of OS running Docker.

Proxy

Problem:

DeGAUSS (or docker run hello-world) returns an error along the lines of x509: certificate signed by unknown authority

Solution

DeGAUSS users from research institutions with networks that contact the internet through a proxy often face this problem. The root problem is that the Docker virtual machine does not have access to the certificates installed on the host machine.

A lot of institutions responsible for protecting PHI will “intercept” incoming and outgoing internet traffic by appending their own certificates in order to sniff the data that is traveling between a computer and the internet on their network. Thus, when a user attempts to use the institution’s network to contact an HTTPS site with a computer that doesn’t have the right security certificates (such as is the case here with the virtual machine running Docker), the browser or download protocol will usually refuse because the mismatched certificates are a red flag that someone is trying to “man in the middle” attack the user. This isn’t a problem unique to Docker — browsing any HTTPS site, e.g. google.com, will return the error if this is the case.

The long fix is to update Docker to utilize the institution's proxy, either through environment variables passed at call time or in the Docker settings. The short fix is to run the Docker commands while connected to a network not connected to a proxy. Assuming this is compliant with the institution’s rules on PHI (it usually is), then you can do this by using your institution’s guest network, your own personal network at home, or another “public” wireless network.

Note that this wouldn’t necessarily require any of the PHI to be on the computer when its connected to non-proxied network. A workaround could be to connect to a different network to docker pull the image and then docker run after switching to the institutional network and adding the data back to the machine. Once an image is pulled, the container can be successfully run without internet access.

Docker Containers for Windows

Problem

Within Windows terminal, trying to pull or run a Docker container results in an error: docker image operating system "linux" cannot be used on this platform

Solution

By default, Docker for Windows is setup to run Windows Containers and is not compatible with Linux Containers. To change this setting, right click on the Docker logo in the toolbar menu and choose Switch to Linux Containers...

Other problems exist with the newer version of Docker for Windows, namely that specifying a host path using the $PWD environment variable no longer works and host paths need to be specified using the full path name with / instead of \ separating the directories.