markusgraf_ch/openspec/changes/archive/2025-10-30-simple-deployment/tasks.md

Tasks: simple-deployment

Implementation Tasks

1. Create deployment script structure

• Create scripts/ directory in project root if it doesn't exist
• Create scripts/deploy.sh with proper shebang and execution permissions
• Add basic script structure with functions for connection, upload, and error handling
• Validates: Script file exists and is executable

2. Implement prerequisite checks

• Check for existence and non-empty state of public/ directory
• Verify rsync is installed and available in PATH
• Check that SSH_USER and SSH_HOST environment variables are set
• Display clear error messages for any missing prerequisites
• Validates: Script exits early with helpful errors when prerequisites are missing

3. Implement SSH/rsync connection logic

• Configure rsync to connect using SSH_USER and SSH_HOST
• Support configurable SSH_PORT (defaults to 22)
• Support configurable REMOTE_ROOT (defaults to /httpsdocs)
• Use SSH key-based authentication for secure, password-less access
• Validates: Script can establish SSH connection with correct credentials

4. Implement file sync functionality

• Use rsync command to sync public/ contents to remote directory
• Configure sync to preserve file permissions and timestamps (-a flag)
• Enable compression during transfer (-z flag)
• Implement mirror behavior with --delete flag (removes remote files not present locally)
• Handle all file types appropriately
• Validates: All files from public/ are correctly synced to the remote directory and old files are removed

5. Add progress and status reporting

• Display connection status messages
• Show sync progress through rsync verbose output
• Report sync completion with summary
• Ensure SSH keys or passwords are never displayed in output
• Validates: User receives clear feedback during deployment process

6. Implement error handling

• Catch connection failures with descriptive error messages
• Handle partial upload failures gracefully
• Provide actionable error messages for common failure scenarios
• Set appropriate exit codes (0 for success, non-zero for failures)
• Validates: Script handles errors gracefully and provides useful feedback

7. Add script documentation

• Add header comments explaining script purpose and usage
• Document required environment variables (SSH_USER, SSH_HOST, SSH_PORT, REMOTE_ROOT)
• Include example usage in comments
• Add inline comments for rsync command options
• Validates: Script is self-documenting for future maintenance

8. Update project documentation

• Add deployment section to README.md or create DEPLOYMENT.md
• Document environment variable setup process
• Provide example deployment workflow (build → deploy)
• Include troubleshooting tips for common issues
• Validates: User documentation exists and covers deployment process

9. Test deployment script

• Test with missing prerequisites (no public/, no rsync, no SSH_USER/SSH_HOST)
• Test with SSH authentication issues
• Test successful deployment with valid credentials and SSH keys
• Verify synced files match local public/ directory
• Verify remote files are deleted when removed locally (mirror behavior)
• Validates: Script behaves correctly in success and failure scenarios

10. Create .gitignore entry for environment files

• Ensure .env files are ignored if user creates them locally
• Verify credentials cannot be accidentally committed
• Validates: Git ignores any credential-containing files

Dependency Notes

• Tasks 1-2 must complete before task 3
• Tasks 3-4 must complete before task 5
• Task 6 can be implemented in parallel with tasks 3-5
• Tasks 7-8 can be done after core implementation (tasks 1-6)
• Task 9 requires all implementation tasks (1-6) to be complete
• Task 10 can be done at any time

Testing Strategy

Manual testing is sufficient for this change:

1. Test prerequisite checks by intentionally removing prerequisites
2. Test with invalid credentials to verify error handling
3. Test successful deployment to production server
4. Verify all files are present and correct on server after deployment
5. Test script output for clarity and absence of credential exposure