SMB share plan

plans/Plan-smb.md

@@ -0,0 +1,85 @@
+# SMB Samba Share Container
+
+Add a general-purpose authenticated SMB share alongside the existing Time Machine container, reusing the same patterns already in place.
+
+## Approach
+
+- Use `dperson/samba` (well-maintained, minimal image with full Samba + Avahi support)
+- `network_mode: host` — same as `timemachine`, required for mDNS/Avahi auto-discovery in Finder
+- Mount `/home/padriano/share` on the host into `/share` in the container
+- Provide a dedicated `smb.conf` at `samba/smb.conf` (new file, mirrors `timemachine/smb.conf` style)
+- Reuse the existing `timemachine/avahi-daemon.conf` (same interface, same settings)
+- New env vars in `.env` / `.env.example`: `SAMBA_USERNAME`, `SAMBA_PASSWORD`, `SAMBA_UID`, `SAMBA_GID`
+
+## Files to change
+
+- `docker-compose.yml` — add `samba` service
+- `samba/smb.conf` — new file, defines the `[Share]` section
+- `.env.example` — add new Samba env vars
+
+## New `samba` service (docker-compose.yml)
+
+```yaml
+samba:
+  image: dperson/samba:latest
+  container_name: samba
+  hostname: samba
+  restart: unless-stopped
+  network_mode: host
+  environment:
+    - USERID=${SAMBA_UID}
+    - GROUPID=${SAMBA_GID}
+    - TZ=${TZ}
+  volumes:
+    - /home/padriano/share:/share
+    - /home/padriano/projects/composer/samba/smb.conf:/etc/samba/smb.conf:ro
+    - /home/padriano/projects/composer/timemachine/avahi-daemon.conf:/etc/avahi/avahi-daemon.conf:ro
+```
+
+## New `samba/smb.conf`
+
+Mirrors the global section of `timemachine/smb.conf` (SMB2/3 only, Apple extensions via `vfs fruit`) but defines a `[Share]` section instead of `[TimeMachine]`:
+
+```ini
+[global]
+  workgroup = WORKGROUP
+  server role = standalone server
+  security = user
+  ntlm auth = no
+  server min protocol = SMB2_10
+  server max protocol = SMB3
+  server signing = auto
+  smb encrypt = desired
+  load printers = no
+  printing = bsd
+  printcap name = /dev/null
+  disable spoolss = yes
+  vfs objects = catia fruit streams_xattr
+  fruit:aapl = yes
+  fruit:metadata = stream
+  fruit:posix_rename = yes
+  logging = file
+  log file = /var/log/samba/log.%m
+  max log size = 1000
+
+[Share]
+  path = /share
+  browseable = yes
+  read only = no
+  create mask = 0664
+  directory mask = 0775
+  valid users = ${SAMBA_USERNAME}
+```
+
+## `.env.example` additions
+
+```
+SAMBA_UID=1000
+SAMBA_GID=1000
+SAMBA_USERNAME=samba
+SAMBA_PASSWORD=replace-with-your-samba-password
+```
+
+## Mac client access
+
+Once running, Mac Finder will auto-discover the share via mDNS. Manual connect: `smb://samba.local/Share` or `smb://<host-ip>/Share`.