tractatus/docs/DEPLOYMENT_RSYNC_PATTERNS.md

Rsync Deployment Patterns for Tractatus

Issue Discovered: 2025-10-14

During Phase 0 security deployment, files were deployed to incorrect locations due to rsync trailing slash behavior.

Problem: Trailing Slash Behavior

Incorrect command (deployed contents to wrong location):

rsync -avz src/middleware/ src/routes/ user@host:/var/www/tractatus/

What happened:

• src/middleware/ with trailing slash = "copy contents of middleware/"
• Files ended up in /var/www/tractatus/ root instead of /var/www/tractatus/src/middleware/
• All middleware and route files were dumped into root directory

Correct Patterns

Pattern 1: Deploy directory contents to matching destination structure

# Deploy middleware files to remote middleware directory
rsync -avz src/middleware/ user@host:/var/www/tractatus/src/middleware/

# Deploy routes files to remote routes directory
rsync -avz src/routes/ user@host:/var/www/tractatus/src/routes/

Key: Trailing slash on both source AND destination = copy contents into destination directory

Pattern 2: Deploy entire directory tree

# Deploy entire src/ directory preserving structure
rsync -avz src/ user@host:/var/www/tractatus/src/

Key: Trailing slash on source, matching destination = preserve structure

Pattern 3: Deploy specific files

# Deploy individual files
rsync -avz src/server.js src/utils/security-logger.js \
  user@host:/var/www/tractatus/src/

Key: No trailing slash on files

Rsync Trailing Slash Rules

Source	Destination	Result
dir/	/dest/	Copies contents of dir into /dest/
dir	/dest/	Creates /dest/dir/ with contents
dir/	/dest/dir/	Copies contents into existing /dest/dir/
file.js	/dest/	Copies file.js into /dest/

Recommended Approach

Use the automated deployment script:

./scripts/deploy-security-middleware.sh

This script uses correct patterns and handles:

• ✅ Directory structure preservation
• ✅ File permissions (D755 for dirs, F644 for files)
• ✅ Service restart
• ✅ Status verification

Manual Deployment (if needed)

# 1. Deploy middleware
rsync -avz --chmod=D755,F644 -e "ssh -i ~/.ssh/tractatus_deploy" \
  src/middleware/ \
  ubuntu@vps-93a693da.vps.ovh.net:/var/www/tractatus/src/middleware/

# 2. Deploy routes
rsync -avz --chmod=D755,F644 -e "ssh -i ~/.ssh/tractatus_deploy" \
  src/routes/ \
  ubuntu@vps-93a693da.vps.ovh.net:/var/www/tractatus/src/routes/

# 3. Deploy server and utils
rsync -avz --chmod=D755,F644 -e "ssh -i ~/.ssh/tractatus_deploy" \
  src/server.js src/utils/security-logger.js \
  ubuntu@vps-93a693da.vps.ovh.net:/var/www/tractatus/src/

# 4. Restart service
ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net \
  "sudo systemctl restart tractatus"

Cleanup After Incorrect Deployment

If files end up in the wrong location:

# SSH to server
ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net

# Remove incorrectly placed files from root
cd /var/www/tractatus
rm -f *.routes.js *.middleware.js index.js

# Verify correct locations
ls src/middleware/*.js
ls src/routes/*.js

# Re-deploy using correct pattern

Prevention

1. Always use the deployment script when possible
2. Test rsync commands with --dry-run first
3. Verify destination paths include full directory structure
4. Remember trailing slash = "contents", no slash = "directory itself"

---

Last Updated: 2025-10-14 Issue Resolved: Files cleaned up and correct deployment script created