name: Deploy (SCP) # Reusable deploy workflow, invoked by continuous_integration.yaml (U5) for both the automatic # test deploy and the opt-in production deploy. One workflow, one input contract, so a second # transport (e.g. FTPS for a future shared-hosting target) can be added later as an alternative # without restructuring this workflow or its callers (FR-02, D-02, NFR-09). on: workflow_call: inputs: host: description: 'Which host to deploy to: the prefix of its secrets, one of SLS_TEST, SLS_PROD, ASF_TEST (_HOST_ADDRESS, _PORT, _USERNAME, _SSH_KEY)' required: true type: string artifact_name: description: 'Build artifact to download and deploy' required: true type: string environment: description: 'Environment label, used in log output and step naming' required: true type: string deploy_path: description: 'Release root on the target host for this environment' required: true type: string service_name: description: 'systemd --user unit to restart after switching releases' required: true type: string health_check_url: description: 'Public /health URL to verify after restart' required: true type: string run_db_backup: description: 'Take a database backup before deploying (production only)' required: false type: boolean default: false transport: description: 'Transport mechanism. Only "scp" is implemented today; reserved for FTPS later' required: false type: string default: scp jobs: deploy: runs-on: linux steps: # Runner-independent: only installs what is missing, and only uses sudo when not already root and sudo exists # (a container on the PC runner has neither sudo nor a need for it; the Pi runner may need it). # # Authentication is by SSH key only (no password). The deploy key of the chosen host (_HOST_SSH_KEY) is # written to a temp directory with mode 600; the wrappers `rssh` / `rscp` below use it (-i, IdentitiesOnly, # BatchMode, StrictHostKeyChecking=accept-new with a known_hosts file of this job only) and read the address, # port and user of the chosen host from files in the same directory, so no other step needs the secrets. The # directory is removed at the end of the job; the key is never printed. # # All twelve secrets are mapped here and the right group is chosen in the shell: an expression like # `a && secrets.X || secrets.Y` would silently fall through to another host when a secret is empty. - name: Ensure ssh tooling and authentication env: TARGET: ${{ inputs.host }} SLS_TEST_HOST_ADDRESS: ${{ secrets.SLS_TEST_HOST_ADDRESS }} SLS_TEST_HOST_PORT: ${{ secrets.SLS_TEST_HOST_PORT }} SLS_TEST_HOST_USERNAME: ${{ secrets.SLS_TEST_HOST_USERNAME }} SLS_TEST_HOST_SSH_KEY: ${{ secrets.SLS_TEST_HOST_SSH_KEY }} SLS_PROD_HOST_ADDRESS: ${{ secrets.SLS_PROD_HOST_ADDRESS }} SLS_PROD_HOST_PORT: ${{ secrets.SLS_PROD_HOST_PORT }} SLS_PROD_HOST_USERNAME: ${{ secrets.SLS_PROD_HOST_USERNAME }} SLS_PROD_HOST_SSH_KEY: ${{ secrets.SLS_PROD_HOST_SSH_KEY }} ASF_TEST_HOST_ADDRESS: ${{ secrets.ASF_TEST_HOST_ADDRESS }} ASF_TEST_HOST_PORT: ${{ secrets.ASF_TEST_HOST_PORT }} ASF_TEST_HOST_USERNAME: ${{ secrets.ASF_TEST_HOST_USERNAME }} ASF_TEST_HOST_SSH_KEY: ${{ secrets.ASF_TEST_HOST_SSH_KEY }} IN_DEPLOY_PATH: ${{ inputs.deploy_path }} IN_SERVICE_NAME: ${{ inputs.service_name }} IN_HEALTH_URL: ${{ inputs.health_check_url }} run: | # Inputs are not secret: print them so an empty one is visible, and stop before anything touches the host. echo "Inputs: host='$TARGET' deploy_path='$IN_DEPLOY_PATH' service_name='$IN_SERVICE_NAME' health_check_url='$IN_HEALTH_URL'" for v in IN_DEPLOY_PATH IN_SERVICE_NAME IN_HEALTH_URL; do if [ -z "${!v}" ]; then echo "Input $v is empty; refusing to deploy."; exit 1; fi done case "$TARGET" in SLS_TEST|SLS_PROD|ASF_TEST) ;; *) echo "Unknown host '$TARGET' (expected SLS_TEST, SLS_PROD or ASF_TEST); refusing to deploy."; exit 1;; esac SSH_HOST_VALUE=$(printenv "${TARGET}_HOST_ADDRESS") SSH_PORT_VALUE=$(printenv "${TARGET}_HOST_PORT") SSH_USER_VALUE=$(printenv "${TARGET}_HOST_USERNAME") SSH_KEY_VALUE=$(printenv "${TARGET}_HOST_SSH_KEY") for n in HOST_ADDRESS HOST_PORT HOST_USERNAME HOST_SSH_KEY; do if [ -z "$(printenv "${TARGET}_${n}")" ]; then echo "The secret ${TARGET}_${n} is empty or not set; refusing to deploy."; exit 1; fi done SUDO="" if [ "$(id -u)" != "0" ] && command -v sudo >/dev/null 2>&1; then SUDO="sudo"; fi if ! command -v ssh >/dev/null 2>&1 || ! command -v scp >/dev/null 2>&1; then $SUDO apt-get update && $SUDO apt-get install -y openssh-client fi D=$(mktemp -d) chmod 700 "$D" mkdir -p "$D/bin" echo "DEPLOY_TMP=$D" >> "$GITHUB_ENV" echo "$D/bin" >> "$GITHUB_PATH" printf '%s\n' "$SSH_KEY_VALUE" > "$D/key" chmod 600 "$D/key" printf '%s' "$SSH_HOST_VALUE" > "$D/host" printf '%s' "$SSH_PORT_VALUE" > "$D/port" printf '%s' "$SSH_USER_VALUE" > "$D/user" : > "$D/known_hosts" cat > "$D/bin/rssh" <<'WRAP' #!/bin/sh D="$(dirname "$0")/.." exec ssh -i "$D/key" -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile="$D/known_hosts" \ -p "$(cat "$D/port")" "$(cat "$D/user")@$(cat "$D/host")" "$@" WRAP cat > "$D/bin/rscp" <<'WRAP' #!/bin/sh # The remote side of a copy is written as @REMOTE@:; it is replaced by user@host. D="$(dirname "$0")/.." REMOTE="$(cat "$D/user")@$(cat "$D/host")" for a in "$@"; do shift; set -- "$@" "$(printf '%s' "$a" | sed "s|^@REMOTE@:|$REMOTE:|")"; done exec scp -i "$D/key" -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=accept-new -o UserKnownHostsFile="$D/known_hosts" \ -P "$(cat "$D/port")" "$@" WRAP chmod +x "$D/bin/rssh" "$D/bin/rscp" # Connection check: fails the job here, with a clear message, instead of in the first real step. if "$D/bin/rssh" true; then echo "Authentication: deploy key accepted by ${TARGET}"; else echo "The deploy key of ${TARGET} was rejected or the host is unreachable."; exit 1; fi - name: Compute release timestamp id: release run: echo "timestamp=$(date -u +%Y%m%d%H%M%S)" >> "$GITHUB_OUTPUT" - name: Download build artifact uses: actions/download-artifact@v3 with: name: ${{ inputs.artifact_name }} path: ${{ inputs.artifact_name }} # Production-only database backup, taken before anything on the host changes (FR-20, D-26). # The backup script itself lives on the host (created once during Operations host setup) and # is only invoked here — no database connection string or credential is ever known to this # workflow, keeping D-16 ("runtime secrets live in host environment variables") intact. # Gitea Actions does not resolve `${{ inputs.* }}` inside a step's `name:` (unlike inside # `run:`, where it works fine — see the echo below) — kept static rather than showing the # literal, unresolved `${{ inputs.environment }}` text in the log. - name: Back up database if: ${{ inputs.run_db_backup }} run: | echo "Environment: ${{ inputs.environment }}" rssh \ "bash ~/scripts/backup-slpsoftware-db.sh ${{ inputs.environment }}" # Uploads the published output to a fresh, timestamped release directory rather than # overwriting the live one (FR-06, D-27) — the atomic switch happens in a later step, once # this upload and the website-symlink step below have both succeeded. # # Plain shell step rather than a container SCP action: container-based actions fail on this # runner with "failed to attach to container: unable to upgrade to tcp, received 409", a known # limitation of Podman's Docker-compatible API for the attach/log-streaming that container # actions rely on (D-05). A plain scp command needs no nested container. # Same Gitea Actions limitation as the step above — static name, value logged via echo instead. - name: Upload release run: | echo "Environment: ${{ inputs.environment }}, transport: ${{ inputs.transport }}" RELEASE_DIR="${{ inputs.deploy_path }}/releases/${{ steps.release.outputs.timestamp }}" rssh \ "mkdir -p $RELEASE_DIR" rscp \ -r ${{ inputs.artifact_name }}/* \ "@REMOTE@:$RELEASE_DIR/" # The customer's public website (wwwroot/web) must survive every CMS deploy (FR-08, ASM-01). # It lives outside the swapped release directory in a persistent shared/ folder, and is # symlinked into each new release. mkdir -p is idempotent, so this is also correct on the very # first-ever deploy, before any website workspace has published anything there (U1 already # tolerates a missing wwwroot/web at startup). The publish output's own wwwroot/web (empty, or # containing only the placeholder page) is removed before the symlink is created, so it never # shadows the persistent content. `mkdir -p $RELEASE_DIR/wwwroot` guards against `ln -s` failing # with "No such file or directory": dotnet publish only emits a wwwroot/ folder at all when the # source project has one with actual content, so a release built before any frontend content # exists can land with no wwwroot/ directory whatsoever, not merely an empty wwwroot/web/. - name: Link persistent website content run: | RELEASE_DIR="${{ inputs.deploy_path }}/releases/${{ steps.release.outputs.timestamp }}" rssh \ "mkdir -p ${{ inputs.deploy_path }}/shared/wwwroot-web && \ mkdir -p $RELEASE_DIR/wwwroot && \ rm -rf $RELEASE_DIR/wwwroot/web && \ ln -s ../../../shared/wwwroot-web $RELEASE_DIR/wwwroot/web" # Optional plugin modules (future modular support): a compiled SlpModularCms.Modules.*.dll # dropped into shared/modules survives every release, the same persistence pattern as # shared/wwwroot-web above — except there's no cross-account permission dance here, since # shared/modules lives entirely under gitea-workflow's own tree (unlike wwwroot-web, which # reaches into webadmin's). ModuleOrchestrator.DiscoverModules() already scans its own base # directory on disk for matching assemblies at startup (SlpModularCms.Core/Hosting/ # ModuleOrchestrator.cs) and loads whatever it finds via reflection — no code change needed, # only somewhere for the DLL to still be after the next deploy replaces releases/{timestamp}. # `ls ... 2>/dev/null` piped to a `while read` (rather than a bare glob loop) keeps this # POSIX-sh safe and correct when shared/modules is empty, which is the common case today. - name: Link persistent modules run: | RELEASE_DIR="${{ inputs.deploy_path }}/releases/${{ steps.release.outputs.timestamp }}" rssh \ "mkdir -p ${{ inputs.deploy_path }}/shared/modules && \ ls ${{ inputs.deploy_path }}/shared/modules/*.dll 2>/dev/null | while read -r f; do \ name=\$(basename \"\$f\"); \ ln -sf \"../../shared/modules/\$name\" \"$RELEASE_DIR/\$name\"; \ done" # Atomic release switch (FR-06, D-27): `ln -sfn` replaces the `current` symlink target in a # single filesystem operation, so there is no moment where `current` points at a half-written # directory. The process is then restarted so it picks up the new assemblies — a running .NET # process holds on to the ones it already loaded. - name: Switch current release and restart service run: | RELEASE_DIR="${{ inputs.deploy_path }}/releases/${{ steps.release.outputs.timestamp }}" rssh \ "ln -sfn $RELEASE_DIR ${{ inputs.deploy_path }}/current && \ systemctl --user restart ${{ inputs.service_name }}" # Verifies the restart actually produced a healthy process before this run is allowed to # report success. Retries absorb process-startup time, which is about 10 seconds normally but # 30 seconds or more when the host is busy (a migration step, two services restarting at once # on one machine): up to 40 attempts, 3 seconds apart (about 2 minutes), each request limited # to 5 seconds so one hanging attempt cannot eat the whole window. A run that never turns # healthy fails the job without touching `current` or pruning (see below) - no automatic # rollback. A previous release is always still on disk to restore from manually (D-26). - name: Verify /health run: | attempts=40 for attempt in $(seq 1 $attempts); do if curl -f -s --max-time 5 -o /dev/null "${{ inputs.health_check_url }}"; then echo "Health check passed on attempt $attempt" exit 0 fi echo "Health check attempt $attempt of $attempts failed, retrying..." sleep 3 done echo "Health check did not pass after $attempts attempts" exit 1 # Retention: keep `current` plus exactly one previous release, so a manual rollback is always # a re-point-and-restart away without rebuilding. Only runs after a passing health check — # pruning after a failed check could leave the only other release as the sole survivor. - name: Prune old releases run: | rssh \ "cd ${{ inputs.deploy_path }}/releases && ls -1t | tail -n +3 | xargs -r rm -rf" - name: Remove deploy key if: always() run: rm -rf "${DEPLOY_TMP:-/nonexistent}"