Here is a comprehensive summary of the entire troubleshooting session for your documentation.

---

Documentation: Nextcloud Permission Fix & Storage Architecture

1. The Issue

Problem: Nextcloud (Official Docker Image) was failing with Permission denied errors when trying to write to the data directory.
Context:

• Storage: SMB Share hosted on NAS (//192.168.xx.xxx/cloud).
• Host Mount: The share was mounted on the Host OS via /etc/fstab as user fullmetal (UID 1000).
• Container User: The official Nextcloud container runs internally as www-data (UID 33).
• Conflict: The Linux kernel blocked the container (UID 33) from writing to the directory owned by the host user (UID 1000) because the permissions were set to 750 (drwxr-x---), which excludes "others."

---

2. The Solution: Docker Native SMB Volume

We rejected changing the Host OS mount (which would break other apps like Plex/Sonarr) and rejected switching to the LinuxServer.io image (to avoid migration).

Implemented Fix:
We configured Docker to create a dedicated, isolated SMB connection specifically for Nextcloud. This allows Nextcloud to connect as UID 33 (www-data) while the rest of the system continues using UID 1000.

Final docker-compose.yml Configuration snippet

# -------------------------------------------------------
# ARCHITECTURE FIX: DEDICATED SMB VOLUME
# -------------------------------------------------------
volumes:
  nextcloud_data:
    driver_opts:
      type: cifs
      # Force the connection to present files as UID 33 (www-data)
      # This bypasses the Host OS permission layer entirely.
      o: "username=NAS_USER,password=NAS_PASS,uid=33,gid=33,file_mode=0770,dir_mode=0770,vers=3.0"
      
      # Deep Path Mounting:
      # We point directly to the /Nextcloud subfolder on the NAS share
      device: "//192.168.xx.xxx/smb-share/Nextcloud"

---

3. Architecture Decision Record (ADR)

Question	Decision	Reasoning
Why not change /etc/fstab?	No	Changing the host mount to uid=33 would fix Nextcloud but break access for all other containers (Plex, Sonarr, etc.) that expect uid=1000.
Why not switch Images?	No	Switching to linuxserver/nextcloud would fix permissions but require migrating the database and config structure.
Why not use Docker volumes for ALL apps?	No	Using Docker volumes for everything creates "Connection Storms" (too many SMB clients), complicates credential management, and is less reliable on reboot than Host OS mounts.

4. Key Learnings

1. Named Volume Limits: Docker named volumes cannot mount subdirectories in the services section (e.g., - myvol/subdir:/data is invalid). You must define the subdirectory in the device path within the volumes section.
2. The "Hybrid" Strategy: The best practice is to continue using Host Mounts (/etc/fstab) for standard apps (Plex, *arrs) and only use Docker Native Volumes for "special" apps with strict user requirements (Nextcloud, Postgres).
3. Maintenance: If the NAS password changes, update it in two places: /etc/fstab (for the host) and docker-compose.yml (for Nextcloud).