Troubleshooting

Docker Issues

Docker not running

Symptoms: “Docker daemon not running” or “Cannot connect to Docker”

Solution:

• Windows/macOS: Start Docker Desktop and wait for green status
• Linux:

  sudo systemctl start docker
  sudo systemctl enable docker
  

Insufficient resources

Symptoms: Slow performance, out of memory errors, failed simulations

Solution:

1. Open Docker Desktop settings -> Go to Resources
2. Allocate: Memory: 32GB minimum
3. Apply and restart Docker

Docker images not downloading

Symptoms: Stuck at “Pulling image” or network timeouts

Solution:

1. Check internet connection
2. Restart Docker Desktop
3. Try manual pull:

   docker pull idossha/simnibs:{version}
   

GUI Display Issues

No GUI appears (Linux)

Solution:

# Allow Docker to access X11
xhost +local:docker

# Check DISPLAY variable
echo $DISPLAY

# If empty, set manually
export DISPLAY=:0

No GUI appears (macOS)

Solution:

1. Ensure [XQuartz 2.7.7] is installed (not newer versions)
2. Log out and back in after XQuartz installation
3. Launch XQuartz from Applications > Utilities
4. Check XQuartz preferences: Allow connections from network clients

If still running into issues, download the config_sys.sh place it next to your loader.sh, and run it:

bash config_sys.sh

No GUI appears (Windows)

Solution:

1. Ensure VcXsrv is running (check system tray)
2. Verify VcXsrv configuration:
   • Multiple windows
   • Start no client
   • “Disable access control” MUST be checked
3. Restart VcXsrv if needed
4. Check Windows Firewall isn’t blocking VcXsrv

Getting Help

Information to Include

When reporting issues, include:

1. System Information:
   • OS version
   • Docker version
   • Available RAM/storage
   • X server version (XQuartz/VcXsrv)
2. Error Details:
   • Exact error messages
   • Steps to reproduce
   • When the error occurs
   • Screenshot if applicable
3. Log Files:
   • Docker logs: docker logs [container_name]
   • Application logs from output directory
   • System logs if relevant

Where to Get Help

1. GitHub Issues - Search existing issues first
2. GitHub Discussions - Community support
3. Documentation - Check other installation guides for platform-specific help

Diagnostic Commands

Run these commands to gather system information:

# System information
uname -a
docker --version
docker info

# Docker status
docker ps
docker images

# Display information
echo $DISPLAY
xhost  # Linux/macOS only

# Resource usage
free -h  # Linux
top      # All platforms