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: 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 media_library_copy: description: 'unchanged | on | off: sets Media__Library__CopyOnStartup in shared/env before the restart. TEST only, never production.' required: false type: string default: unchanged media_library_dual_write: description: 'unchanged | on | off: sets Media__Library__DualWrite (the write-through of phase 2) in shared/env before the restart. TEST only, never production.' required: false type: string default: unchanged 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: the Pi-Main host only allows password login from the Pi runner's address, so every runner other # than that one needs a key. If the secret PI_MAIN_SSH_KEY (private key of the deploy account) is set and works, # the wrappers `rssh` / `rscp` below use it (-i, IdentitiesOnly, BatchMode); otherwise they fall back to sshpass # with the password, which keeps working from the Pi runner. The key lives in a temp directory that is removed # at the end of the job; it is never printed. - name: Ensure ssh tooling and authentication env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} SSH_KEY: ${{ secrets.PI_MAIN_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: 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 SUDO="" if [ "$(id -u)" != "0" ] && command -v sudo >/dev/null 2>&1; then SUDO="sudo"; fi if ! command -v sshpass >/dev/null 2>&1 || ! command -v ssh >/dev/null 2>&1 || ! command -v scp >/dev/null 2>&1; then $SUDO apt-get update && $SUDO apt-get install -y sshpass openssh-client fi D=$(mktemp -d) mkdir -p "$D/bin" echo "DEPLOY_TMP=$D" >> "$GITHUB_ENV" echo "$D/bin" >> "$GITHUB_PATH" if [ -n "$SSH_KEY" ]; then printf '%s\n' "$SSH_KEY" > "$D/key" chmod 600 "$D/key" if ssh -i "$D/key" -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=no -o ConnectTimeout=15 \ -p "$SSH_PORT" "$SSH_USER@$SSH_HOST" true; then touch "$D/key_ok" echo "Authentication: deploy key" else echo "Deploy key rejected or host unreachable with it; falling back to password" fi else echo "No deploy key set; using password" fi cat > "$D/bin/rssh" <<'WRAP' #!/bin/sh D="$(dirname "$0")/.." if [ -f "$D/key_ok" ]; then exec ssh -i "$D/key" -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=no -p "$SSH_PORT" "$SSH_USER@$SSH_HOST" "$@" fi exec sshpass -p "$SSH_PASS" ssh -o StrictHostKeyChecking=no -p "$SSH_PORT" "$SSH_USER@$SSH_HOST" "$@" WRAP cat > "$D/bin/rscp" <<'WRAP' #!/bin/sh D="$(dirname "$0")/.." if [ -f "$D/key_ok" ]; then exec scp -i "$D/key" -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=no -P "$SSH_PORT" "$@" fi exec sshpass -p "$SSH_PASS" scp -o StrictHostKeyChecking=no -P "$SSH_PORT" "$@" WRAP chmod +x "$D/bin/rssh" "$D/bin/rscp" - 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 }} env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} 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 env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} 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 }}/* \ "$SSH_USER@$SSH_HOST:$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 env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} 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 env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} 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" # The media library copy switch (migration plan of the media library, decision 13): the application reads # Media__Library__CopyOnStartup from the host environment file shared/env (D-16). The deploy account can edit that file, # nobody else needs a shell on the host. Only this ONE key is touched (nothing else of the file is read or printed, the # file holds secrets), only on a test environment, and only with a value that is exactly on, off or unchanged. # `on` makes the next start copy the photos into the library's tables and verify the copy (log line # "Media library copy verified: N photos and M uses"); `off` removes the key again (the default is off). - name: Set the media library copy switch (test only) if: inputs.media_library_copy != 'unchanged' env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} run: | MODE="${{ inputs.media_library_copy }}" if [ "${{ inputs.environment }}" != "test" ]; then echo "The media library copy switch is for the test environment only (environment: ${{ inputs.environment }})." >&2 exit 1 fi if [ "$MODE" != "on" ] && [ "$MODE" != "off" ]; then echo "media_library_copy must be unchanged, on or off (got: $MODE)." >&2 exit 1 fi ENV_FILE="${{ inputs.deploy_path }}/shared/env" if [ "$MODE" = "on" ]; then rssh "touch $ENV_FILE && sed -i '/^Media__Library__CopyOnStartup=/d' $ENV_FILE && echo 'Media__Library__CopyOnStartup=true' >> $ENV_FILE" else rssh "touch $ENV_FILE && sed -i '/^Media__Library__CopyOnStartup=/d' $ENV_FILE" fi echo "Media__Library__CopyOnStartup is now: $(rssh "grep '^Media__Library__CopyOnStartup=' $ENV_FILE || echo '(not set = off)'")" # The write-through switch of phase 2 (same rules as the copy switch above: only this one key of shared/env, only on test, # only on, off or unchanged). `on` makes every change of the hero also land in the library's tables. - name: Set the media library write-through switch (test only) if: inputs.media_library_dual_write != 'unchanged' env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} run: | MODE="${{ inputs.media_library_dual_write }}" if [ "${{ inputs.environment }}" != "test" ]; then echo "The media library write-through switch is for the test environment only (environment: ${{ inputs.environment }})." >&2 exit 1 fi if [ "$MODE" != "on" ] && [ "$MODE" != "off" ]; then echo "media_library_dual_write must be unchanged, on or off (got: $MODE)." >&2 exit 1 fi ENV_FILE="${{ inputs.deploy_path }}/shared/env" if [ "$MODE" = "on" ]; then rssh "touch $ENV_FILE && sed -i '/^Media__Library__DualWrite=/d' $ENV_FILE && echo 'Media__Library__DualWrite=true' >> $ENV_FILE" else rssh "touch $ENV_FILE && sed -i '/^Media__Library__DualWrite=/d' $ENV_FILE" fi echo "Media__Library__DualWrite is now: $(rssh "grep '^Media__Library__DualWrite=' $ENV_FILE || echo '(not set = off)'")" # 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 env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} 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 }}" # After a restart with the copy on, show the verification line of the copy in this run's log (the journal of the user # service), so nobody needs a shell on the host to see "Media library copy verified: N photos and M uses". - name: Report the media library copy (test only) if: inputs.media_library_copy == 'on' env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} run: | sleep 20 rssh "journalctl --user -u ${{ inputs.service_name }} --since '-10 min' --no-pager 2>/dev/null | grep -E 'Media library copy|media library copy' | tail -5 || true" echo "Look for 'Media library copy verified: N photos and M uses'. An error line means the copy was rolled back and nothing was copied." # 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 env: SSH_USER: ${{ secrets.PI_MAIN_USERNAME }} SSH_PASS: ${{ secrets.PI_MAIN_PASSWORD }} SSH_PORT: ${{ secrets.PI_MAIN_PORT }} SSH_HOST: ${{ secrets.PI_MAIN_ADDRESS }} 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}"