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

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

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

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

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)

Solution 2: Modify Colima Mount Configuration

Change the mount type to 9p with permission mapping:

colima start --mount-type 9p --cpu 4 --memory 8

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

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

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

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

References

• Docker Volume Management
• Colima Documentation
• PostgreSQL Image on Docker Hub

---