This page should be a collection of tips and tricks related to using Docker via CLI.

Using UI through a Docker Container (macOS)

MacOS has stricter security and if you need to use xQuartz.

Install xQuartz on your Mac (if you haven't already) using homebrew: brew install xquartz 

Run the following script to set up xQuartz:

defaults write org.xquartz.X11 nolisten_tcp -bool false
defaults write org.xquartz.X11 no_auth -bool false
defaults write org.xquartz.X11 enable_iglx -bool true

mkdir -p ~/.xinitrc.d

cat << 'EOF' > ~/.xinitrc.d/xhost-config.sh
#!/bin/sh

xhost +127.0.0.1
xhost +localhost
xhost +\$(hostname)
EOF

chmod +x ~/.xinitrc.d/xhost-config.sh

open -a XQuartz

With any X11 Forwarding, you need to make sure the DISPLAY  environment variable is set up appropriately. Below is an example Docker command-line:

docker run -it --rm -e DISPLAY=host.docker.internal:0 your-image

The host.docker.internal  is the Mac's local IP address on the Docker networking (unless you have changed the default IP address, it should be 192.168.65.1.


If you want to test to make sure this works, you can build your own x11-apps image with the following Dockerfile :

FROM debian:latest

RUN apt-get update && apt-get install -y x11-apps
RUN rm -rf /tmp/* /usr/share/doc/* /usr/share/info/* /var/tmp/*
RUN useradd -ms /bin/bash user
ENV DISPLAY :0

USER user
ENTRYPOINT ["/bin/sh", "-c", "$0 \"$@\"", "xeyes"]

Run: docker buildx build -t my-xeyes /path/to/Dockerfile 

Then run: docker run -it --rm -e DISPLAY=host.docker.internal:0 my-xeyes 


Using Docker context

With the use of Docker Desktop and Docker CLI, they can show two different behaviors based upon the docker context . A context is basically a way to view various damon setups.

For example, below shows 3 contexts associated with the default cli, desktop, and OrbStack:

$ docker context ls
NAME              DESCRIPTION                               DOCKER ENDPOINT                                  ERROR
default           Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
desktop-linux *   Docker Desktop                            unix:///Users/<user>/.docker/run/docker.sock
orbstack          OrbStack                                  unix:///Users/<user>/.orbstack/run/docker.sock

Note: * signifies the context used in the terminal

A typical issue would be if you run Docker Desktop, and it shows certain images or containers, but docker cli does not. This means that you're in the wrong context!

Some scripts may require certain context to be set. It is highly suggested that if you use Docker Desktop, to make sure your context is set to desktop-linux  over default.

  • No labels