chore: archive completed OpenSpec changes
Archive all 6 deployed changes following OpenSpec workflow: - add-minimal-hugo-site → hugo-site spec - add-multilingual-support → internationalization spec - migrate-site-content → content-migration + image-assets specs - add-custom-bootstrap-styling → styling spec - add-cv-page → content-management spec - simple-deployment → deployment spec All changes moved to archive/ with 2025-10-30 date prefix. Created 7 capability specs reflecting deployed functionality. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
@@ -0,0 +1,21 @@
|
||||
# Change Proposal: simple-deployment
|
||||
|
||||
## Why
|
||||
Currently there is no automated way to deploy the built Hugo site to the production server. Manual file transfers are error-prone and time-consuming. This change adds a deployment script to automate uploads via rsync over SSH, properly mirroring content (including deletions).
|
||||
|
||||
## What Changes
|
||||
- Add deployment script `scripts/deploy.sh` that syncs `public/` directory via rsync
|
||||
- Use environment variables `SSH_USER`, `SSH_HOST`, `SSH_PORT`, and `REMOTE_ROOT` for configuration
|
||||
- Implement mirror behavior with `--delete` flag to remove remote files not present locally
|
||||
- Implement prerequisite checks (public/ exists, rsync installed, credentials set)
|
||||
- Add error handling and progress reporting
|
||||
- Update documentation with deployment instructions
|
||||
|
||||
## Impact
|
||||
- Affected specs: New `deployment` capability
|
||||
- Affected code: New file `scripts/deploy.sh`
|
||||
- Dependencies: Requires `rsync` to be installed
|
||||
- Configuration: User must set `SSH_USER` and `SSH_HOST` environment variables
|
||||
- `SSH_PORT` defaults to 22
|
||||
- `REMOTE_ROOT` defaults to /httpsdocs
|
||||
- No changes to existing Hugo templates, content, or build process
|
||||
@@ -0,0 +1,98 @@
|
||||
# Deployment Capability
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Rsync Deployment Script SHALL be provided
|
||||
The system SHALL provide an automated deployment script that syncs the built Hugo site to the production server via rsync over SSH, properly mirroring content.
|
||||
|
||||
#### Scenario: User deploys site after building
|
||||
**Given** the Hugo site has been built successfully (public/ directory exists)
|
||||
**And** the user has set the SSH_USER and SSH_HOST environment variables
|
||||
**When** the user runs the deployment script
|
||||
**Then** the script connects to the specified SSH_HOST via rsync over SSH
|
||||
**And** syncs all files from the public/ directory to the REMOTE_ROOT directory on the server
|
||||
**And** deletes remote files that don't exist locally (mirror behavior)
|
||||
**And** displays sync progress and completion status
|
||||
**And** exits with status code 0 on success
|
||||
|
||||
#### Scenario: Script fails when credentials are missing
|
||||
**Given** the Hugo site has been built
|
||||
**And** the SSH_USER or SSH_HOST environment variable is not set
|
||||
**When** the user runs the deployment script
|
||||
**Then** the script displays an error message explaining the missing configuration
|
||||
**And** exits with a non-zero status code
|
||||
**And** does not attempt to connect to the server
|
||||
|
||||
#### Scenario: Script handles connection failures gracefully
|
||||
**Given** the SSH_USER and SSH_HOST are set correctly
|
||||
**And** the network connection to the server is unavailable or SSH authentication fails
|
||||
**When** the user runs the deployment script
|
||||
**Then** the script displays a clear error message about the connection failure
|
||||
**And** exits with a non-zero status code
|
||||
**And** does not leave the deployment in a partially completed state
|
||||
|
||||
### Requirement: Secure Credential Management SHALL be enforced
|
||||
The deployment process SHALL handle credentials securely without exposing them in version control or script output.
|
||||
|
||||
#### Scenario: Configuration stored as environment variables
|
||||
**Given** the user needs to deploy the site
|
||||
**When** the user reviews the deployment documentation
|
||||
**Then** the documentation instructs them to set SSH_USER, SSH_HOST, SSH_PORT, and REMOTE_ROOT as environment variables
|
||||
**And** the deployment script reads configuration only from environment variables
|
||||
**And** credentials are never hardcoded in scripts or configuration files
|
||||
**And** SSH key-based authentication is used for secure, password-less access
|
||||
|
||||
#### Scenario: Script does not expose credentials in output
|
||||
**Given** the deployment script is running
|
||||
**When** the script displays status messages or logs
|
||||
**Then** SSH keys or passwords are never displayed in plain text
|
||||
**And** connection strings show only the host and user information
|
||||
**And** error messages do not reveal credential values
|
||||
|
||||
### Requirement: Deployment Status Feedback SHALL be provided
|
||||
The deployment script SHALL provide clear feedback about the deployment process and outcome.
|
||||
|
||||
#### Scenario: User receives progress updates during deployment
|
||||
**Given** the deployment script is uploading files
|
||||
**When** the upload is in progress
|
||||
**Then** the script displays which files or directories are being uploaded
|
||||
**And** shows overall progress indicators
|
||||
**And** provides estimated time or completion percentage when possible
|
||||
|
||||
#### Scenario: Successful deployment confirmation
|
||||
**Given** all files have been uploaded successfully
|
||||
**When** the deployment completes
|
||||
**Then** the script displays a success message
|
||||
**And** confirms the total number of files uploaded
|
||||
**And** exits with status code 0
|
||||
|
||||
#### Scenario: Failed deployment with actionable error
|
||||
**Given** an error occurs during deployment
|
||||
**When** the deployment fails
|
||||
**Then** the script displays the specific error encountered
|
||||
**And** suggests possible remediation steps
|
||||
**And** exits with a non-zero status code
|
||||
|
||||
### Requirement: Deployment Prerequisites SHALL be verified
|
||||
The deployment script SHALL verify that prerequisites are met before attempting deployment.
|
||||
|
||||
#### Scenario: Script checks for built site
|
||||
**Given** the user runs the deployment script
|
||||
**When** the script starts
|
||||
**Then** it verifies that the public/ directory exists
|
||||
**And** contains files to deploy
|
||||
**And** exits with an error if the directory is missing or empty
|
||||
|
||||
#### Scenario: Script checks for required tools
|
||||
**Given** the deployment script starts
|
||||
**When** it performs prerequisite checks
|
||||
**Then** it verifies that rsync is installed and available
|
||||
**And** displays an installation message if rsync is missing
|
||||
**And** exits with an error if required tools are unavailable
|
||||
|
||||
#### Scenario: Script supports configurable ports and remote directories
|
||||
**Given** the user needs to deploy to a non-standard SSH port or directory
|
||||
**When** the user sets SSH_PORT and REMOTE_ROOT environment variables
|
||||
**Then** the script uses the specified port instead of the default (22)
|
||||
**And** the script uploads to the specified remote directory instead of the default (/httpsdocs)
|
||||
**And** if these variables are not set, the script uses sensible defaults
|
||||
@@ -0,0 +1,88 @@
|
||||
# Tasks: simple-deployment
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
### 1. Create deployment script structure
|
||||
- [x] Create `scripts/` directory in project root if it doesn't exist
|
||||
- [x] Create `scripts/deploy.sh` with proper shebang and execution permissions
|
||||
- [x] Add basic script structure with functions for connection, upload, and error handling
|
||||
- **Validates**: Script file exists and is executable
|
||||
|
||||
### 2. Implement prerequisite checks
|
||||
- [x] Check for existence and non-empty state of `public/` directory
|
||||
- [x] Verify `rsync` is installed and available in PATH
|
||||
- [x] Check that `SSH_USER` and `SSH_HOST` environment variables are set
|
||||
- [x] 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
|
||||
- [x] Configure rsync to connect using SSH_USER and SSH_HOST
|
||||
- [x] Support configurable SSH_PORT (defaults to 22)
|
||||
- [x] Support configurable REMOTE_ROOT (defaults to /httpsdocs)
|
||||
- [x] Use SSH key-based authentication for secure, password-less access
|
||||
- **Validates**: Script can establish SSH connection with correct credentials
|
||||
|
||||
### 4. Implement file sync functionality
|
||||
- [x] Use rsync command to sync `public/` contents to remote directory
|
||||
- [x] Configure sync to preserve file permissions and timestamps (-a flag)
|
||||
- [x] Enable compression during transfer (-z flag)
|
||||
- [x] Implement mirror behavior with --delete flag (removes remote files not present locally)
|
||||
- [x] 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
|
||||
- [x] Display connection status messages
|
||||
- [x] Show sync progress through rsync verbose output
|
||||
- [x] Report sync completion with summary
|
||||
- [x] Ensure SSH keys or passwords are never displayed in output
|
||||
- **Validates**: User receives clear feedback during deployment process
|
||||
|
||||
### 6. Implement error handling
|
||||
- [x] Catch connection failures with descriptive error messages
|
||||
- [x] Handle partial upload failures gracefully
|
||||
- [x] Provide actionable error messages for common failure scenarios
|
||||
- [x] Set appropriate exit codes (0 for success, non-zero for failures)
|
||||
- **Validates**: Script handles errors gracefully and provides useful feedback
|
||||
|
||||
### 7. Add script documentation
|
||||
- [x] Add header comments explaining script purpose and usage
|
||||
- [x] Document required environment variables (SSH_USER, SSH_HOST, SSH_PORT, REMOTE_ROOT)
|
||||
- [x] Include example usage in comments
|
||||
- [x] Add inline comments for rsync command options
|
||||
- **Validates**: Script is self-documenting for future maintenance
|
||||
|
||||
### 8. Update project documentation
|
||||
- [x] Add deployment section to README.md or create DEPLOYMENT.md
|
||||
- [x] Document environment variable setup process
|
||||
- [x] Provide example deployment workflow (build → deploy)
|
||||
- [x] Include troubleshooting tips for common issues
|
||||
- **Validates**: User documentation exists and covers deployment process
|
||||
|
||||
### 9. Test deployment script
|
||||
- [x] Test with missing prerequisites (no public/, no rsync, no SSH_USER/SSH_HOST)
|
||||
- [x] Test with SSH authentication issues
|
||||
- [x] Test successful deployment with valid credentials and SSH keys
|
||||
- [x] Verify synced files match local public/ directory
|
||||
- [x] 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
|
||||
- [x] Ensure .env files are ignored if user creates them locally
|
||||
- [x] 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
|
||||
Reference in New Issue
Block a user