documentation

DEPLOYMENT_UPDATE.md

@@ -0,0 +1,166 @@
+# Deployment Update Guide
+
+## Steps to Update Your Deployed Application
+
+### 1. Commit and Push Your Changes (From Your Local Machine)
+
+```powershell
+# Navigate to your project directory
+cd C:\Users\NateEmmert\pdf-rename-sort\pdf-rename-sort
+
+# Add all changes
+git add .
+
+# Commit with a descriptive message
+git commit -m "Add file archiving system with download/delete, security fixes, and resource cleanup"
+
+# Push to your remote repository
+git push origin main
+```
+
+### 2. Update Code on Your Server
+
+SSH into your server and run:
+
+```bash
+# Navigate to your application directory
+cd /path/to/pdf-rename-sort
+
+# Pull the latest changes
+git pull origin main
+
+# Activate your virtual environment (if you have one)
+source venv/bin/activate
+
+# Install any new dependencies (if needed)
+pip install -r requirements.txt
+```
+
+### 3. Create the Archives Directory
+
+```bash
+# Create the archives directory if it doesn't exist
+mkdir -p archives
+chmod 755 archives
+```
+
+### 4. Restart the Application
+
+**If using systemd service:**
+```bash
+sudo systemctl restart pdf-renamer
+sudo systemctl status pdf-renamer
+```
+
+**If running manually:**
+```bash
+# Stop the current process (Ctrl+C or kill the process)
+# Then restart
+python pdf_renamer.py
+```
+
+**If using Gunicorn:**
+```bash
+# Find the process
+ps aux | grep pdf_renamer
+
+# Kill it
+sudo kill -HUP <PID>
+
+# Or restart the service
+sudo systemctl restart pdf-renamer-gunicorn
+```
+
+### 5. Verify the Updates
+
+1. **Check the logs:**
+   ```bash
+   sudo journalctl -u pdf-renamer -f
+   # Or if logging to a file:
+   tail -f /var/log/pdf-renamer.log
+   ```
+
+2. **Test the application:**
+   - Visit your application URL
+   - Log in with Microsoft Entra ID
+   - Upload a PDF and process it
+   - Verify the ZIP is created in the `archives/` folder
+   - Test downloading the ZIP
+   - Test deleting the job
+
+3. **Check file permissions:**
+   ```bash
+   ls -la archives/
+   ls -la processed/
+   ```
+
+### 6. Monitor for Issues
+
+Watch the logs for any errors:
+```bash
+# Follow system logs
+sudo journalctl -u pdf-renamer -f
+
+# Or check nginx error logs
+sudo tail -f /var/log/nginx/error.log
+```
+
+## Key Changes in This Update
+
+1. **File Archiving System:** ZIPs now saved to `archives/` folder
+2. **Automatic Cleanup:** Temporary files removed after ZIP creation
+3. **Download Feature:** Users can download ZIPs from archives
+4. **Delete Feature:** Comprehensive cleanup when jobs are deleted
+5. **Security Fixes:** Path traversal protection, MIME validation
+6. **Resource Management:** Proper cleanup of PDF streams and temp directories
+7. **Performance:** Batched disk I/O for job persistence
+
+## Rollback (If Needed)
+
+If something goes wrong:
+
+```bash
+# Go back to previous commit
+git log --oneline  # Find the previous commit hash
+git checkout <previous-commit-hash>
+
+# Restart the service
+sudo systemctl restart pdf-renamer
+```
+
+## Optional: Setup Automatic Cleanup
+
+Add a cron job to clean up old jobs (optional):
+
+```bash
+# Edit crontab
+crontab -e
+
+# Add this line to run cleanup daily at 2 AM
+0 2 * * * cd /path/to/pdf-rename-sort && /path/to/venv/bin/python -c "from pdf_renamer import cleanup_old_jobs; cleanup_old_jobs()"
+```
+
+## Troubleshooting
+
+**Permission Issues:**
+```bash
+sudo chown -R www-data:www-data archives/
+sudo chown -R www-data:www-data processed/
+```
+
+**Missing Dependencies:**
+```bash
+pip install --upgrade -r requirements.txt
+```
+
+**Service Won't Start:**
+```bash
+# Check for syntax errors
+python -m py_compile pdf_renamer.py
+
+# Check service status
+sudo systemctl status pdf-renamer
+
+# View detailed logs
+sudo journalctl -u pdf-renamer --no-pager -n 100
+```