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