DEV Community

chatgptnexus
chatgptnexus

Posted on

Solving Permission Issues with PostgreSQL and Docker Compose on macOS Using Colima

#colima #lima #docker #postgres

When setting up PostgreSQL using Docker Compose on macOS with Colima, you might encounter permission issues when trying to map container data directories to host paths via bind mounts. A common error you might see is:

chown: changing ownership of '/var/lib/postgresql/data': Permission denied
Enter fullscreen mode Exit fullscreen mode

This problem stems from the discrepancy between host and container user permissions. Here's a detailed analysis and solutions:

Problem Analysis

1. Immediate Manifestation of Permission Issues

Using a typical Docker Compose configuration like this:

services: postgres: image: postgres volumes: - ./pgdata:/var/lib/postgresql/data
Enter fullscreen mode Exit fullscreen mode

you'll notice that the PostgreSQL container tries to change the ownership of /var/lib/postgresql/data to the postgres user (UID/GID=999). However, the host's mapped directory permissions might not allow this change due to a mismatch in user IDs.

2. The Specificity of Colima

Colima runs containers inside a Linux VM (defaulting to Lima), where file system mounts (virtiofs or sshfs) can lead to inconsistent UID/GID mappings:

  • The macOS user (e.g., 501:20) doesn't match the VM's default lima user (UID=1000).
  • The PostgreSQL container runs as postgres (UID=999), causing conflicts with host directory permissions.

3. Limitations of Bind Mounts

Bind mounts directly link host directories to container paths but struggle with cross-system user permission mappings:

  • The permission models between macOS (APFS) and Linux (in the VM) differ significantly.
  • If the container's UID/GID doesn't match the host's, write permissions are denied.

Solutions

Solution 1: Force Specify Container User (Recommended)

Explicitly declare the user that the container should run as in docker-compose.yml:

services: postgres: image: postgres user: "501:20" # Replace with host UID/GID, obtained via `id -u` and `id -g` volumes: - ./pgdata:/var/lib/postgresql/data
Enter fullscreen mode Exit fullscreen mode

Principle:

  • This forces the container to operate with the host user's identity, bypassing permission conflicts.
  • For dynamic UID/GID, use build arguments: 
 docker compose build --build-arg UID=$(id -u) --build-arg GID=$(id -g)
Enter fullscreen mode Exit fullscreen mode

Solution 2: Modify Colima Mount Configuration

Change the mount type to 9p with permission mapping:

colima start --mount-type 9p --cpu 4 --memory 8
Enter fullscreen mode Exit fullscreen mode

Edit the Colima configuration file (~/.colima/default/colima.yaml):

mountType: 9p mounts: - location: ~/pgdata writable: true 9p: securityModel: mapped-xattr cache: mmap
Enter fullscreen mode Exit fullscreen mode

Use Case:

  • Best for scenarios requiring complex, long-term mount structures.

Alternative Approaches Comparison

Method Advantages Disadvantages
Specify user attribute Directly resolves permission issues Requires manual UID/GID management
Use Docker Volumes Automatic permission handling, reliable persistence Inconvenient log access, need to enter container
Change mount to 9p Better system compatibility Potential I/O performance impact

Understanding Colima's Permission Mapping

Colima uses a VM where lima (UID=1000) does not match the macOS user (e.g., UID=501). This mismatch, combined with bind mounts, leads to permission issues as the container tries to access host directories with its own user identity.

Core Issue:

  • Opaque user mapping across systems: Lack of automatic UID/GID synchronization from host to VM to container.
  • Differing file system permission models: macOS vs. Linux handling of permissions.

Best Practices

  1. Use user attribute first: Hardcode or dynamically inject host UID/GID in docker-compose.yml.
  2. Limit use of Bind Mounts: Only use when direct host file access is needed, ensuring permission alignment.
  3. Optimize log access: Use docker logs or mount a specific log directory: 
 volumes: - ./logs:/var/log/postgresql
Enter fullscreen mode Exit fullscreen mode

Implementing these strategies can help resolve permission issues while keeping your development environment straightforward.

References

Top comments (0)