fix rsync permissions: setup-server.sh with setgid dirs, exclude .claude/.pi

docs/SERVER_SETUP.md

@@ -1,18 +1,42 @@
 # Server Setup
 
-## One-time setup on server
+## One-time setup (before first deploy)
+
+Run the setup script on the server. It creates `/var/www/posterg`, sets the
+correct ownership/permissions, and adds the deploy user to the `posterg` group:
 
 ```bash
-ssh posterg
-sudo mkdir -p /var/www/posterg
-sudo chown www-data:posterg /var/www/posterg
-sudo chmod 775 /var/www/posterg
-exit
+just setup-server
 ```
 
-## Deploying the application
+What the script does:
+- Creates the `posterg` group if it doesn't exist
+- Adds both the SSH user (read from `~/.ssh/config` via `ssh -G posterg`) and `www-data` to `posterg`
+- Creates `/var/www/posterg` owned by `www-data:posterg`
+- Sets all directories to **2775** (`rwxrws r-x`) — the setgid bit ensures
+  new files/dirs inherit the `posterg` group, which is required for
+  `rsync --chown=www-data:posterg` to succeed
+- Sets files to **664**
+- Sets `storage/` to **2775**, database files to **660**
 
-Files are pushed via rsync — there is no repo on the server.
+> **Important:** After running `setup-server`, log out and back in on the server
+> (or run `newgrp posterg`) so the new group membership is active before deploying.
+
+### Why setgid (2775) on directories?
+
+rsync uses `--chown=www-data:posterg` to set ownership on transferred files.
+For this to work, the receiving process (running as `padlock`) must have write
+permission on every target directory. Without the setgid bit:
+- Newly created subdirectories inherit `padlock`'s primary group
+- `www-data` (nginx/php-fpm) can't write to them → 403 errors
+- `padlock` can't write to dirs owned by `www-data` → rsync Permission denied
+
+With `2775 + group=posterg`:
+- Both `padlock` and `www-data` are in `posterg` → both can write
+- New subdirs automatically get `posterg` as their group
+- rsync can create files and directories without errors
+
+## Deploying the application
 
 ```bash
 # Push all app files
@@ -24,7 +48,8 @@ just deploy-db
 
 ## Applying the nginx config
 
-The config is in `nginx/posterg.conf`. Upload it and run the deploy script on the server:
+The config is in `nginx/posterg.conf`. Upload it and run the deploy script on
+the server:
 
 ```bash
 rsync -v nginx/posterg.conf posterg:/tmp/posterg.conf
@@ -32,8 +57,8 @@ ssh posterg "sudo bash /var/www/posterg/scripts/deploy-server.sh"
 ssh posterg "sudo systemctl reload nginx"
 ```
 
-`scripts/deploy-server.sh` fixes ownership/permissions and installs the nginx config
-from `/tmp/posterg.conf`. It must be run as root.
+`scripts/deploy-server.sh` fixes ownership/permissions and installs the nginx
+config from `/tmp/posterg.conf`. It must be run as root.
 
 ## Managing admin users
 
@@ -41,24 +66,51 @@ from `/tmp/posterg.conf`. It must be run as root.
 ssh posterg "sudo bash /var/www/posterg/scripts/manage-admin-users.sh"
 ```
 
-This is an interactive menu for adding, changing, and deleting htpasswd entries
-at `/etc/nginx/.htpasswd-posterg`.
+Interactive menu for adding, changing, and deleting htpasswd entries at
+`/etc/nginx/.htpasswd-posterg`.
 
 ## Troubleshooting
 
-### Nginx 403 Forbidden
+### rsync: Permission denied on mkdir or mkstemp
+
+The remote directory permissions are wrong. Run:
+
+```bash
+just setup-server
+```
+
+Then log out/in on the server and retry `just deploy`.
+
+If you need to fix it manually (replace `youruser` with your remote username):
+
+```bash
+ssh posterg
+sudo DEPLOY_USER=youruser bash /tmp/setup-server.sh
+```
+
+Or directly:
+
 ```bash
 ssh posterg
 sudo chown -R www-data:posterg /var/www/posterg
-sudo find /var/www/posterg -type d -exec chmod 755 {} \;
-sudo find /var/www/posterg -type f -exec chmod 644 {} \;
-sudo chmod 775 /var/www/posterg/storage
+sudo find /var/www/posterg -type d -exec chmod 2775 {} \;
+sudo find /var/www/posterg -type f -exec chmod 664 {} \;
+sudo usermod -aG posterg youruser
+```
+
+### Nginx 403 Forbidden
+
+```bash
+ssh posterg
+sudo find /var/www/posterg -type d -exec chmod 2775 {} \;
+sudo find /var/www/posterg -type f -exec chmod 664 {} \;
 sudo chmod 660 /var/www/posterg/storage/*.db
 ```
 
 ### Database permission error
+
 ```bash
 ssh posterg
-sudo chown www-data:posterg /var/www/posterg/storage/test.db
-sudo chmod 660 /var/www/posterg/storage/test.db
+sudo chown www-data:posterg /var/www/posterg/storage/posterg.db
+sudo chmod 660 /var/www/posterg/storage/posterg.db
 ```