feat: add OpenSpec proposal for FTPS deployment
Create proposal for automated deployment script that uploads the Hugo site to www.markusgraf.ch via FTPS. Includes: - Deployment capability spec with 4 main requirements - Implementation tasks for scripts/deploy.sh - Secure credential management via environment variables 🤖 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,18 @@
|
|||||||
|
# Change Proposal: add-ftps-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 FTPS uploads to www.markusgraf.ch.
|
||||||
|
|
||||||
|
## What Changes
|
||||||
|
- Add deployment script `scripts/deploy.sh` that uploads `public/` directory via FTPS
|
||||||
|
- Use environment variable `FTPS_PASSWORD` for secure credential management
|
||||||
|
- Implement prerequisite checks (public/ exists, lftp 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 `lftp` tool to be installed
|
||||||
|
- Configuration: User must set `FTPS_PASSWORD` environment variable
|
||||||
|
- No changes to existing Hugo templates, content, or build process
|
||||||
@@ -0,0 +1,89 @@
|
|||||||
|
# Deployment Capability
|
||||||
|
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: FTPS Deployment Script SHALL be provided
|
||||||
|
The system SHALL provide an automated deployment script that uploads the built Hugo site to the production server via FTPS.
|
||||||
|
|
||||||
|
#### Scenario: User deploys site after building
|
||||||
|
**Given** the Hugo site has been built successfully (public/ directory exists)
|
||||||
|
**And** the user has set the FTPS_PASSWORD environment variable
|
||||||
|
**When** the user runs the deployment script
|
||||||
|
**Then** the script connects to www.markusgraf.ch via FTPS using the username "gurix"
|
||||||
|
**And** uploads all files from the public/ directory to the httpsdocs/ directory on the server
|
||||||
|
**And** displays upload 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 FTPS_PASSWORD environment variable is not set
|
||||||
|
**When** the user runs the deployment script
|
||||||
|
**Then** the script displays an error message explaining the missing credential
|
||||||
|
**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 FTPS_PASSWORD is set correctly
|
||||||
|
**And** the network connection to www.markusgraf.ch is unavailable or 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: Credentials 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 FTPS_PASSWORD as an environment variable
|
||||||
|
**And** the deployment script reads credentials only from environment variables
|
||||||
|
**And** credentials are never hardcoded in scripts or configuration files
|
||||||
|
|
||||||
|
#### Scenario: Script does not expose credentials in output
|
||||||
|
**Given** the deployment script is running
|
||||||
|
**When** the script displays status messages or logs
|
||||||
|
**Then** the password is never displayed in plain text
|
||||||
|
**And** connection strings mask the password portion
|
||||||
|
**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 lftp is installed and available
|
||||||
|
**And** displays an installation message if lftp is missing
|
||||||
|
**And** exits with an error if required tools are unavailable
|
||||||
@@ -0,0 +1,86 @@
|
|||||||
|
# Tasks: add-ftps-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 `lftp` is installed and available in PATH
|
||||||
|
- Check that `FTPS_PASSWORD` environment variable is set
|
||||||
|
- Display clear error messages for any missing prerequisites
|
||||||
|
- **Validates**: Script exits early with helpful errors when prerequisites are missing
|
||||||
|
|
||||||
|
### 3. Implement FTPS connection logic
|
||||||
|
- Configure lftp connection to www.markusgraf.ch with username "gurix"
|
||||||
|
- Use `FTPS_PASSWORD` environment variable for authentication
|
||||||
|
- Set FTPS-specific lftp settings (SSL/TLS requirements)
|
||||||
|
- Implement connection timeout and retry logic
|
||||||
|
- **Validates**: Script can establish FTPS connection with correct credentials
|
||||||
|
|
||||||
|
### 4. Implement file upload functionality
|
||||||
|
- Use lftp mirror command to upload `public/` contents to `httpsdocs/`
|
||||||
|
- Configure upload to preserve file permissions and timestamps
|
||||||
|
- Enable parallel transfers for improved performance
|
||||||
|
- Handle special files (symlinks, hidden files) appropriately
|
||||||
|
- **Validates**: All files from public/ are correctly uploaded to httpsdocs/
|
||||||
|
|
||||||
|
### 5. Add progress and status reporting
|
||||||
|
- Display connection status messages
|
||||||
|
- Show upload progress (file counts, current file being uploaded)
|
||||||
|
- Report upload completion with summary statistics
|
||||||
|
- Ensure password is 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
|
||||||
|
- Include example usage in comments
|
||||||
|
- Add inline comments for complex lftp commands
|
||||||
|
- **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 lftp, no password)
|
||||||
|
- Test with incorrect credentials
|
||||||
|
- Test successful deployment with valid credentials
|
||||||
|
- Verify uploaded files match local public/ directory
|
||||||
|
- **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
|
||||||
Reference in New Issue
Block a user