Platform Guides

Docker installation and platform-specific configuration for Windows, macOS, and Linux.

Windows

Install Docker Desktop

Download Docker Desktop from docker.com
Run the installer — enable WSL 2 backend when prompted (recommended over Hyper-V)
Restart if prompted
Launch Docker Desktop and wait for it to start

If WSL 2 is not already installed:

wsl --install
# Restart, then ensure Docker Desktop uses WSL 2
# Settings > General > "Use the WSL 2 based engine"

Resource Allocation

With WSL 2, resources are managed via .wslconfig. Create or edit %USERPROFILE%\.wslconfig:

%USERPROFILE%.wslconfig

[wsl2]
memory=4GB   # Personal: 2GB, Pro: 4GB, Enterprise: 8GB
processors=4

Restart WSL after changes: wsl --shutdown

Path Format

Use forward slashes in SOPHON_DATA. Docker does not handle Windows backslashes in volume mounts:

.env

# Correct
SOPHON_DATA=C:/Users/enesh/.sophon

# Wrong — backslashes cause mount errors
SOPHON_DATA=C:\Users\enesh\.sophon

Docker Socket

Docker Desktop for Windows maps /var/run/docker.sock automatically via the WSL 2 backend. No group_add configuration needed.

If using the Hyper-V backend (legacy), the socket mount may not work. Either switch to WSL 2 or remove the socket volume to use the process sandbox fallback.

Firewall

Windows Defender Firewall may prompt when Docker binds ports. Allow access for com.docker.backend on private networks.

macOS

Install Docker Desktop

brew install --cask docker

Works on both Intel and Apple Silicon Macs.

Resource Allocation

Open Docker Desktop > Settings > Resources:

Personal: 2 GB RAM, 2 CPUs
Pro: 4 GB RAM, 4 CPUs
Enterprise: 8 GB RAM, 6 CPUs

Enable VirtioFS for better volume performance: Settings > General > "Use VirtioFS". This is the default on modern Docker Desktop versions.

Docker Socket

Docker Desktop for Mac proxies the Docker socket through a VM. No group_add configuration needed.

Apple Silicon Notes

Sophon's Docker images are multi-arch (linux/amd64 + linux/arm64). No emulation needed.
PostgreSQL, Qdrant, Redis, and RabbitMQ all have native arm64 images.
Ollama GPU access: If you run Ollama for local LLMs, install the native macOS app for Metal GPU acceleration. Docker containers on macOS cannot access the GPU. Configure Sophon to connect to http://host.docker.internal:11434.

Ubuntu / Debian

Install Docker Engine

# Add Docker's official GPG key and repository
sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) \
  signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add current user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker run --rm hello-world

Docker Socket Permissions

Find your Docker group ID and set it in .env:

# Get Docker GID
getent group docker | cut -d: -f3
# Example output: 998

.env

SOPHON_DATA=/home/user/.sophon
DOCKER_GID=998

Add group_add to the gateway service in your compose file:

services:
  sophon-gateway:
    # ... other config ...
    group_add:
      - "${DOCKER_GID:-999}"

Firewall (UFW)

sudo ufw allow 8080/tcp   # Dashboard
sudo ufw allow 8081/tcp   # Gateway API

Fedora / RHEL

Install Docker Engine

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo \
  https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

SELinux

If you get "Permission denied" on volume mounts, add the :z suffix to volumes:

volumes:
  - ${SOPHON_DATA}:/home/sophon/.sophon:z

Or configure SELinux for Docker:

sudo setsebool -P container_manage_cgroup on

Firewall (firewalld)

sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --permanent --add-port=8081/tcp
sudo firewall-cmd --reload

Arch Linux

Install Docker

sudo pacman -S docker docker-compose
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER
newgrp docker

Docker socket setup is the same as Ubuntu/Debian — find the GID with getent group docker | cut -d: -f3 and set DOCKER_GID in your .env.

Platform Guides

On this page