Troubleshooting Docker Issues

Docker Not Detected

Symptom: The Dermi Atlas Manager requirements check shows the Docker row as Not detected, with the message that the Docker client is not available.

Solutions:

1. Is it running? Check for the Docker whale icon in the system tray (Windows) or menu bar (macOS).
2. Install/Reinstall: Ensure Docker is installed and running. On Windows and macOS, install Docker Desktop. On Linux, install Docker Engine. For step-by-step instructions, see Installing Docker for Dermi Atlas Professional.
3. Linux Permissions: Ensure the user account is in the docker group (sudo usermod -aG docker $USER).
4. Minimum version: Dermi Atlas Professional requires Docker version 28.0.0 or newer. If the requirements check reports that the installed version is too old, upgrade Docker and re-run the check.
5. Re-check: After installing or starting Docker, return to the requirements check and click Refresh.

Docker Desktop Will Not Start

Symptom: Docker hangs on "Starting..."

Solutions:

1. Restart: Quit Docker Desktop fully and reopen.
2. Windows WSL: Run wsl --shutdown in PowerShell (Admin) and restart Docker.
3. Reset: Use the "Reset to factory defaults" option in Docker Troubleshoot settings (Warning: Deletes data).

Insufficient Resources

Symptom: Dermi Atlas Professional runs slowly or crashes.

Solution:

1. On macOS and Windows, open Docker Desktop and go to Settings => Resources. On Linux with Docker Engine, there is no Docker Desktop UI, so ensure the host itself has sufficient free RAM and disk.
2. Increase Memory to at least the 4GB minimum, and 8GB or more is recommended.
3. On macOS and Windows, ensure the Docker Desktop virtual disk image has at least the platform minimum of 20GB free, and 100GB or more is recommended.
4. On macOS and Windows, click Apply & restart.

The System Memory requirements check reflects total host RAM, not the Docker Desktop allocation. Increasing the Docker Desktop memory allocation affects runtime performance but does not change what the check reports. For full requirements, see System Requirements for Dermi Atlas.

Increasing the memory available to Docker helps only when the host or Docker itself is memory-constrained. The Atlas Vision service that performs image alignment is capped at 2GB by the deployed stack, so a larger allocation does not raise that ceiling.

Installation Stops at "Installing system"

Symptom: The Dermi Atlas Manager installation passes the requirements check but fails partway through the progress bar, during the "Installing system" step, with "Failed to install Docker images".

Cause: At this step Dermi Atlas Manager downloads about 4GB of container images and loads them into Docker. The requirements check measures free space on the computer, not the space Docker Desktop reserves for itself, so the load fails when the Docker virtual disk is full.

Solution:

1. Docker disk: In Docker Desktop, open Settings => Resources and raise the Disk usage limit to 64GB or more, then click Apply & restart.
2. Still failing: Send the message shown under the progress bar and the Dermi Atlas Manager log files to support; see Troubleshooting Dermi Atlas for where the log files are kept.

ARM64 Processors and Emulation Errors

Symptom: On a Windows on ARM (ARM64) computer, the Network Gateway container logs io_setup() failed (38: Function not implemented), and Dermi Atlas Professional does not run reliably.

Cause: Dermi Atlas Professional container images are published for amd64 (x64) only. On Windows on ARM, Docker Desktop runs amd64 images through QEMU emulation. Running Dermi Atlas Professional under emulation is not supported, even when individual containers appear to start.

Solution:

1. x64 Windows or Linux: Deploy Dermi Atlas Professional on an Intel or AMD (x64) computer.
2. Apple Silicon Mac: Apple Silicon (ARM64) Macs are supported, because Docker Desktop on macOS translates the amd64 images with Rosetta 2 rather than emulating them. In Docker Desktop, open Settings => General, scroll to Virtual Machine Options, select Apple Virtualization framework as the Virtual Machine Manager, and tick Use Rosetta for x86_64/amd64 emulation on Apple Silicon. Rosetta is not available with the Docker VMM option.

Native ARM64 container images are not provided. For the supported platforms, see Hardware and Software Requirements.