From 4dc968e37f96c5b4d539591bf09cf39af612b2e9 Mon Sep 17 00:00:00 2001 From: Markus Graf Date: Tue, 28 Oct 2025 10:38:12 +0100 Subject: [PATCH] feat: add OpenSpec proposal for FTPS deployment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../changes/add-ftps-deployment/proposal.md | 18 ++++ .../specs/deployment/spec.md | 89 +++++++++++++++++++ openspec/changes/add-ftps-deployment/tasks.md | 86 ++++++++++++++++++ 3 files changed, 193 insertions(+) create mode 100644 openspec/changes/add-ftps-deployment/proposal.md create mode 100644 openspec/changes/add-ftps-deployment/specs/deployment/spec.md create mode 100644 openspec/changes/add-ftps-deployment/tasks.md diff --git a/openspec/changes/add-ftps-deployment/proposal.md b/openspec/changes/add-ftps-deployment/proposal.md new file mode 100644 index 0000000..1e00a15 --- /dev/null +++ b/openspec/changes/add-ftps-deployment/proposal.md @@ -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 diff --git a/openspec/changes/add-ftps-deployment/specs/deployment/spec.md b/openspec/changes/add-ftps-deployment/specs/deployment/spec.md new file mode 100644 index 0000000..3bda08e --- /dev/null +++ b/openspec/changes/add-ftps-deployment/specs/deployment/spec.md @@ -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 diff --git a/openspec/changes/add-ftps-deployment/tasks.md b/openspec/changes/add-ftps-deployment/tasks.md new file mode 100644 index 0000000..c54cb22 --- /dev/null +++ b/openspec/changes/add-ftps-deployment/tasks.md @@ -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