asp-classic-unified-framework/docs/deployment-configuration.md

Deployment Configuration

Repository configuration versus machine configuration

public/web.config in the repository is a development/template configuration. Production values are machine-owned and must not be committed.

On the first release deployment, scripts/install-iis-release.ps1 copies the currently active site's complete public\web.config to:

<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:

• ConnectionString, especially the Access Data Source path;
• Environment;
• EnableErrorLogging and ErrorLogPath;
• cache, timeout, and UI settings;
• any host-specific rewrite behavior.

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 settings owned by deployment

The host installer changes only:

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.