ci: isolate deployment from existing IIS sites

docs/deployment-configuration.md

@@ -1,77 +1,82 @@
 # Deployment Configuration
 
-## Repository configuration versus machine configuration
+## Dedicated defaults
 
-`public/web.config` in the repository is a development/template configuration.
-Production values are machine-owned and must not be committed.
+The deployment controller and host installer use the same isolated defaults:
 
-On the first release deployment, `scripts/install-iis-release.ps1` copies the
-currently active site's complete `public\web.config` to:
+| Parameter | Default |
+| --- | --- |
+| `SiteName` | `AspClassicUnifiedFramework` |
+| `AppPoolName` | `AspClassicUnifiedFramework` |
+| `DeployRoot` | `D:\Deployments\AspClassicUnifiedFramework` |
+| `BindingIpAddress` | `100.97.39.23` |
+| `BindingPort` | `8085` |
+| `HostHeader` | empty |
+| `ExpectedBranch` | `master` (controller) |
+
+Every value can be explicitly overridden. Site and pool names, deployment root, and host header containing `Schedulicious` are rejected as an additional safety boundary. The scripts do not enumerate another site as a configuration source and provide no adoption switch.
+
+## Configuration ownership
+
+Repository `public\web.config` is the default template for first deployment. After the package is safely extracted and validated, the host installer initializes:
 
 ```text
 <DeployRoot>\shared\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 machine values include:
+from the staged package's `public\web.config`. If `InitialWebConfigPath` is supplied on that first deployment, the validated host-local file at that path is used instead. The parameter does not replace an existing shared configuration. Configuration is never copied from another IIS site.
 
-- `ConnectionString`, especially the Access `Data Source` path;
-- `Environment`;
-- `EnableErrorLogging` and `ErrorLogPath`;
-- cache, timeout, and UI settings;
-- any host-specific rewrite behavior.
+Every staged release receives the shared file before promotion. Change the shared file only through normal host configuration/change control and validate its XML. Keep secrets and production database paths out of source control.
 
-Change the shared file only through the host's normal configuration-change and
-backup process. Validate that it is well-formed XML before deployment.
+## IIS state owned by the pipeline
 
-## IIS settings owned by deployment
+The pipeline owns only the named dedicated site and app pool. It may:
 
-The host installer changes only:
+1. create them, only when both are absent and only after a staged release validates;
+2. point the dedicated site at `<DeployRoot>\releases\<release-id>\public`;
+3. set `system.webServer/asp enableParentPaths=true` at that site's location;
+4. start/recycle the dedicated app pool and start a newly created site.
 
-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 alter unrelated sites, app pools, bindings, authentication, identities, ACLs, Windows features, or IIS modules. It does not add bindings to an existing site.
 
-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.
+When the target already exists, the site and pool must both exist and exactly match the requested app pool, sole HTTP binding, and pipeline-owned release-public path. Any mismatch fails closed.
 
-## Deployment parameters
+## Controller parameters
 
-Controller (`scripts/deploy-iis-git.ps1`):
+`scripts/deploy-iis-git.ps1` supports:
 
-- `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.
+- `SiteName`, `AppPoolName`, `DeployRoot`, `BindingIpAddress`, `BindingPort`, `HostHeader`: dedicated target identity and binding.
+- `InitialWebConfigPath`: optional host-local first-deployment seed.
+- `RemoteTarget`, `RemotePort`: OpenSSH transport.
+- `SourcePath`: standalone checkout to validate/package.
+- `ExpectedBranch`: remains `master` by default.
 - `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.
+- `BaseUrl`: explicit host-side smoke-test URL.
+- `KeepReleases`: reporting threshold only; no deletion.
+- `LocalPreflightOnly`: local source/XML/package/safety validation; no network.
+- `PreflightOnly` (`HostPreflightOnly` and `RemotePreflightOnly` aliases): run local/package checks, then stream the installer over SSH for host validation without writing remote files or changing IIS/deployment state.
+- `DryRun`: local package validation plus remote command preview; no network.
+- `AllowAnyBranch`, `AllowDirty`: reviewed provenance exceptions.
+- `RunMigrations`: explicit database migration opt-in.
+- `SkipSmokeTest`: explicit smoke-test exception.
+- `Rollback` and `RollbackTo`: switch the dedicated target to a validated prior release.
+
+## Host installer parameters
+
+`scripts/install-iis-release.ps1` accepts the same target/configuration parameters plus:
+
+- `PackagePath`, `ReleaseId`, `ExpectedSha256`: deployment artifact inputs.
+- `PreflightOnly` or `DryRun`: read-only host checks; the target may be absent.
+- `RollbackTo`: validated release ID for rollback.
+
+Host preflight requires elevation and verifies WebAdministration, Classic ASP feature and `AspModule`, URL Rewrite, requested binding conflicts (including wildcard overlap), shared-pool conflicts, deployment drive/path accessibility, names, and exact existing-target state. It makes no IIS or deployment-root changes.
+
+## Failure scope
+
+If creation or smoke testing fails, the installer removes only a site or app pool whose creation flags were set by that invocation. For an existing valid target, it restores the captured physical path and parent-path value. Unrelated IIS resources are never cleanup candidates.
+
+Package staging/release files can remain as diagnostic evidence. Database migrations and external writes are outside IIS rollback.
+
+## Secrets, identity, and writable data
+
+Use OpenSSH configuration, an SSH agent, or a CI secret store. Do not commit passwords, private keys, production connection strings, or database files. Put production databases and logs outside release directories. App-pool identity and filesystem ACL provisioning are explicit host-administration tasks, not inferred from another site.