Resolving Docker Mount Permission Errors with Colima

If you’ve encountered a frustrating error while working with Colima on MacOS, you’re not alone. The error message:

Gracefully stopping... (press Ctrl+C again to force)
Error response from daemon: error while creating mount source path '/Users/<username>/Projects/GPT/application/core-data': chown /Users/<username>/Projects/GPT/application/core-data: operation not permitted

is a common issue faced by developers. It occurs due to permission problems when Colima attempts to access certain directories. Here’s a step-by-step guide on how I resolved this problem using Colima.

Understanding the Issue

The core of the issue lies in Colima inability to change the ownership of the specified directory. This usually happens due to restrictive macOS permissions. However, it requires a bit of configuration to handle directory permissions correctly.

Solution Overview

To resolve the issue, you need to configure Colima to use the 9p mount type and explicitly define the directory mounts both with absolute paths and with the ~ notation. This ensures that Colima can correctly map and cache the directories, granting the necessary permissions.

Step-by-Step Solution

Step 1: Update Colima Configuration

First, you need to update the Colima configuration file. Open or create the override configuration file at /Users/<username>/.colima/_lima/_config/override.yaml. Replace <username> with your actual macOS username.

Add the following configuration to the file:

mountType: 9p
mounts:
  - location: "/Users/<username>"
    writable: true
    9p:
      securityModel: mapped-xattr
      cache: mmap
  - location: "~"
    writable: true
    9p:
      securityModel: mapped-xattr
      cache: mmap
  - location: /tmp/colima
    writable: true
    9p:
      securityModel: mapped-xattr
      cache: mmap

This configuration ensures that both the absolute path and the home directory symbol (~) are correctly mapped and accessible.

Step 2: Restart Colima

After updating the configuration, restart Colima to apply the changes. Use the following commands in your terminal:

colima delete
colima start --mount-type 9p

The colima delete command stops and removes the existing Colima instance, while colima start --mount-type 9p restarts it with the new mount type and configuration.

Explanation of Configuration

• mountType: 9p: Specifies the use of the 9p protocol for mounts. This protocol allows for better handling of file permissions and caching.
• location: Defines the directories to be mounted. Both the absolute path (/Users/<username>) and the home directory symbol (~) are included to cover all scenarios.
• writable: true: Ensures that the directories are writable.
• securityModel: mapped-xattr: Uses extended attributes for security, mapping file permissions appropriately.
• cache: mmap: Specifies the caching mechanism to improve performance.

Conclusion

By configuring Colima to handle directory mounts correctly, you can resolve permission errors and ensure a smoother development experience on macOS. This guide provides a straightforward solution to a common problem, enabling you to focus on your projects without interruption.

Feel free to share this guide with your peers and help others overcome the same challenge. Happy coding!