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

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

- `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.