Run Distr 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?

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.

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.

Prerequisites

Before you begin, make sure you have:

• A macOS system with admin access
• Docker Desktop installed
• Access to the Distr platform

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

Note

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. Verify the Docker Context

Caution

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.

Check the current Docker context, run:

docker context ls

Expected output:

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

If Docker is set to the desktop-linux context, you might encounter errors in the container logs like:

unable to get image 'postgres:17.3-alpine3.20': Cannot connect to the Docker daemon at unix:///Users/jakepage/.docker/run/docker.sock. Is the docker daemon running?

3. Set the Docker Context to default

To switch the Docker context to default, run:

docker context use default

Expected output:

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

4. Update the Docker Config File

If you’re using the Distr agent on macOS, note that it does not rely on Docker’s credential store (credStore). Having this setting in your Docker configuration can sometimes cause authentication issues. To prevent potential errors, it’s best to remove the credStore entry from the Docker config file entirely.

How to fix it

1. Check your current Docker config file

   Run the following command to inspect your configuration:

   cat ~/.docker/config.json

   If you see an entry like this:

   {
       "auths": {},
       "credStore": "desktop"
   }

   You’ll need to remove the credStore line.

2. Open the config file in a text editor

   Use nano to edit the Docker configuration:

   nano ~/.docker/config.json

3. 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": {}
   }

4. Save the file

   • Press CTRL + X to exit.
   • Press Y to confirm saving the changes.
   • Press Enter to save with the same filename.

5. Verify the change

   Run:

   cat ~/.docker/config.json

   Ensure that the credStore line is no longer present.

Removing the credStore setting ensures that the Distr agent operates without credential store conflicts, reducing potential authentication issues.

6. 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.