Run Distr Agents on macOS

Distr is designed to be as versatile as possible. That involves being able to run on a variety of operating systems successfully. While most enterprise environments run on Linux-based VMs, there are always exceptions. What if, for testing purposed, for instance, macOS is the chosen operating system for running Distr agents?

Note

When we talk about “running Distr,” we’re specifically referring to running the Distr agents. Since Distr can also be self-hosted, much of this guide could apply to running Distr in a local Docker environment as well. However, we’ll focus on the SaaS version of Distr and properly configuring a local MacOS target environment to deploy applications through Distr.

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 to ensure a smooth deployment experience.

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

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 agent’s data. If it exists, you need to delete it.

Delete the volume, run:

docker volume rm distr_scratch

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 default
docker context ls

Tip

The currently configured context is marked with an *, which should be next to default.

Verify the current Docker context is set to default:

NAME            DESCRIPTION                               DOCKER ENDPOINT
default *       Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
desktop-linux   Docker Desktop                            unix:///Users/you/.docker/run/docker.sock

3. Disable credStore usage for authentication

If you’re using the Distr agent on macOS, docker uses macOS’s credential manager (credStore). As the Distr agent does not have access to your user credential manager, we need to disable that feature. It’s best to remove the credStore entry from the Docker config file entirely that will configure Docker to store registry authentications in a file which the agent has access to.

Open the config file in a text editor

Use open -e to edit the Docker configuration in your text editor:

open -e ~/.docker/config.json

Remove the credStore line

Inside the file, find the line that contains:

"credStore": "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

To verify everything is configured correctly, try deploying an application through Distr. If there are no errors related to Docker socket access, your setup is good to go.

---

With these steps, your macOS environment should be fully configured to run Distr agents without issues. If you encounter any problems, feel free to reach out to us on Discord or via email at support@glasskube.com.