markusgraf_ch/openspec/specs/deployment/spec.md

# deployment Specification

## Purpose
TBD - created by archiving change simple-deployment. Update Purpose after archive.
## 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