diff --git a/docs/deployment-configuration.md b/docs/deployment-configuration.md index e1749cc..51186d4 100644 --- a/docs/deployment-configuration.md +++ b/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 \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 `\releases\\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 `\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.