markusgraf_ch/openspec/changes/add-ftps-deployment/specs/deployment/spec.md

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