ci: update docs/deployment-configuration.md

docs/deployment-configuration.md

@@ -1,35 +1,77 @@
 # Deployment Configuration
 
-**Date:** 2026-03-11T11:59:39Z
+## Repository configuration versus machine configuration
 
-## Hosting Model
+`public/web.config` in the repository is a development/template configuration.
+Production values are machine-owned and must not be committed.
 
-- Windows IIS
-- `public/` configured as the site root
-- `public/Default.asp` as the default document
-- URL Rewrite sends non-static requests through the ASP front controller
+On the first release deployment, `scripts/install-iis-release.ps1` copies the
+currently active site's complete `public\web.config` to:
 
-## Runtime Configuration
+```text
+<DeployRoot>\shared\public.web.config
+```
 
-Primary deployment configuration is stored in `public/web.config`.
+Every staged release receives that preserved file before IIS is switched. This
+protects the production database path and all other machine-specific settings
+from replacement by repository defaults.
 
-### Important Settings
+Important machine values include:
 
-- `ConnectionString`
-- `Environment`
-- `FlashMessageTimeout`
-- `Error404RedirectSeconds`
-- `CacheExpirationYear`
-- `EnableErrorLogging`
-- `ErrorLogPath`
+- `ConnectionString`, especially the Access `Data Source` path;
+- `Environment`;
+- `EnableErrorLogging` and `ErrorLogPath`;
+- cache, timeout, and UI settings;
+- any host-specific rewrite behavior.
 
-## Deployment Notes
+Change the shared file only through the host's normal configuration-change and
+backup process. Validate that it is well-formed XML before deployment.
 
-- The Access DB path must be updated for the target machine.
-- `ErrorLogPath` should be writable by the IIS application identity if enabled.
-- Static assets are expected under `public/` paths excluded from rewrite rules.
+## IIS settings owned by deployment
 
-## Observed Gaps
+The host installer changes only:
 
-- No container, CI/CD, or infrastructure-as-code deployment config was detected.
-- Deployment is currently documented as a manual IIS-based process.
+1. the selected site's `system.webServer/asp enableParentPaths` value, applied
+   explicitly at the site's location in `applicationHost.config`;
+2. the selected site's `physicalPath`, set to `<release>\public`;
+3. the existing app pool's running state, by starting or recycling it.
+
+It does not create the site, alter bindings, change authentication, change the
+app-pool identity, grant filesystem permissions, install Windows features, or
+install IIS URL Rewrite.
+
+## Deployment parameters
+
+Controller (`scripts/deploy-iis-git.ps1`):
+
+- `SiteName` (required): existing IIS site name.
+- `RemoteTarget`: SSH/Tailscale target; defaults to `webserver-1`.
+- `RemotePort`: defaults to 22.
+- `ExpectedBranch`: defaults to `master`, the repository's current default branch.
+- `DeployRoot`: optional host release root override.
+- `BaseUrl`: local-to-host smoke-test URL.
+- `ReleaseId`: optional immutable release identifier.
+- `KeepReleases`: retention reporting threshold; no automatic deletion.
+- `RemotePreflightOnly`: connect and perform host checks without IIS/release
+  changes.
+- `DryRun`: local-only validation/package simulation; makes no network call.
+- `RunMigrations`: explicit opt-in; never implied.
+- `Rollback` plus `RollbackTo`: switch to an existing release.
+
+Host installer (`scripts/install-iis-release.ps1`):
+
+- `PackagePath`: ZIP produced by the controller.
+- `ExpectedSha256`: transfer integrity check.
+- `PreflightOnly` or `DryRun`: checks without host changes.
+- `SkipSmokeTest`: explicit exception for sites that cannot be probed locally.
+
+## Secrets and identity
+
+No secret parameter is provided. Use OpenSSH configuration, an SSH agent, or a
+CI credential store for the private key. Restrict the deploy key and Tailscale
+ACL to the specific worker and host. Do not put passwords, keys, production
+connection strings, or database files into CI logs or repository files.
+
+The production database and writable logs should live outside immutable release
+directories. Grant the existing IIS app-pool identity only the minimum access
+required for those paths.