Run Distr Controllers on macOS
Distr can run on a variety of operating systems. Most enterprise environments run on Linux-based VMs, but there are exceptions. For example, you might choose macOS as the target for running Distr controllers during testing.
If you’re using Windows or Linux, the Quickstart guide should cover everything you need. But if you’re setting up Distr on macOS, follow these steps.
Prerequisites
Section titled “Prerequisites”1. Install Docker Desktop
Section titled “1. Install Docker Desktop”First, install Docker Desktop for Mac. Follow the installation instructions provided by Docker.
1.1 Delete Distr volume on Docker Desktop
Section titled “1.1 Delete Distr volume on Docker Desktop”If you’ve already tried to install Distr on Docker Desktop and failed to
deploy an application, a volume named distr_scratch has been created. This
volume is used to store the Distr controller’s data. If it exists, you need to
delete it.
Delete the volume, run:
docker volume rm distr_scratch2. Set the Docker Context to default
Section titled “2. Set the Docker Context to default”When Docker Desktop runs on macOS, it creates a lightweight Linux VM, and the
desktop-linux context points to the Docker daemon within this VM. However,
Distr expects to connect to the default Docker socket
(/var/run/docker.sock). This mismatch can cause connectivity issues,
especially when pulling or deploying container images. Setting the context to
default aligns the Docker CLI with the expected Docker endpoint, ensuring
Distr can interact with the Docker daemon properly.
Set the current Docker context to default, run:
docker context use defaultdocker context lsVerify the current Docker context is set to default:
NAME DESCRIPTION DOCKER ENDPOINTdefault * Current DOCKER_HOST based configuration unix:///var/run/docker.sockdesktop-linux Docker Desktop unix:///Users/you/.docker/run/docker.sockAlternative: configure the endpoint on the deployment target
Instead of switching contexts, you can tell the controller which socket to use. Check Use a custom Docker endpoint on the deployment target and enter the endpoint of the context you want to use, for example unix:///Users/you/.docker/run/docker.sock for desktop-linux. See Custom Docker Endpoint.
3. Docker Swarm only: disable credsStore
Section titled “3. Docker Swarm only: disable credsStore”Docker Compose deployments pull images with credentials the Distr controller keeps itself, so they need no change here.
Restarting a Docker Swarm service, however, reads your Docker config, which on macOS points to the macOS credential
manager (credsStore) that the controller cannot reach.
For Docker Swarm, remove the credsStore entry, so that Docker keeps registry credentials in the config file instead.
Open the config file in a text editor
Use open -e to edit the Docker configuration in your text editor:
open -e ~/.docker/config.jsonRemove the credsStore line
Inside the file, find the line that contains:
"credsStore": "desktop"Delete this line entirely, ensuring you don’t leave a trailing comma that could cause JSON parsing errors.
After editing, your file should look something like this:
{ "auths": {}}Remember to save and close the file.
4. Test the Setup
Section titled “4. Test the Setup”To verify everything is configured correctly, try creating a deployment through Distr. If there are no errors related to Docker socket access, your setup is good to go.
After these steps, your macOS environment should be ready to run Distr controllers. If you run into problems, get help in our community forum or email us at support@distr.sh.
Common Issues
Section titled “Common Issues”As the Distr controller is primarily designed for Linux server environments, macOS support is limited and for demo purposes only. Deployment logs are collected as on Linux, but metrics are not.
Metrics collection must be disabled
Section titled “Metrics collection must be disabled”Metrics collection is not supported on macOS due to Docker Desktop’s virtualized filesystem not supporting the required mount propagation. When creating or editing a deployment target for macOS, make sure to disable metrics collection in the deployment target settings.