# Overview

The deployment is broken into **discrete stages** that can be run in any combination. This allows you to, for example, only run validation, or only run post-deploy checks, without triggering a full deployment.

Entry point call:

``` powershell
Invoke-Deployment.ps1 -Customer ROMAC -Environment DEV -Stages VALIDATE,PREDEPLOY,DEPLOY,POSTDEPLOY
```

# Stage Summary

| Stage         | Script (Tier 2)       | Safe to Run Alone? | Notes                     |
| ------------- | --------------------- | ------------------ | ------------------------- |
| VALIDATE      | `Validation.psm1`     | Yes — read only    | No changes made           |
| PREREQUISITES | `Prerequisites.psm1`  | Yes — read only    | No changes made           |
| PREDEPLOY     | `PreDeployment.psm1`  | Yes (with care)    | Stages files, no swap yet |
| DEPLOY        | `Deployment.psm1`     | No — destructive   | Requires PREDEPLOY first  |
| POSTDEPLOY    | `PostDeployment.psm1` | Yes (after DEPLOY) | Checks only, no changes   |

# Stage 1 — VALIDATE

## Purpose

Load the manifest and verify it is well-formed and consistent before anything else happens.

## What It Does

  - Reads the manifest file for the given customer/environment
  - Checks all required fields are present
  - Validates server names, version references, and flags
  - Checks that the referenced build artifact version exists
  - Fails fast with a clear error if anything is wrong

## What It Does NOT Do

  - Makes no changes to any server
  - Does not connect to target servers (it may ping/resolve names only)

## Why It Exists Separately

You might want to validate a new manifest you've written without triggering a full deployment. Running VALIDATE alone takes seconds and gives you confidence before committing to the rest.

# Stage 2 — PREREQUISITES

## Purpose

Verify that the target environment meets all requirements before deployment begins.

## What It Checks (Not Exhaustive — Full List TBC)

  - Required software is installed on target servers (e.g. .NET runtime, SQL client)
  - Correct environment labels/flags are set up
  - Services exist (so the deployment can stop/start them)
  - Network connectivity between agent and target servers
  - Sufficient disk space on target servers
  - Database is accessible
  - If DEPLOY will include DB: check `dacpacReady` flag (see [[ESP Database]])

## Outcome

  - Pass: continue to next stage
  - Fail: abort with a clear list of what's missing — **no changes made**

# Stage 3 — PREDEPLOY

## Purpose

Prepare the new version's files on the target servers **without** switching anything live. Think of it as laying everything out ready before the actual switch.

## What It Does

  - Copies build artifacts from the AzDO artifact store to a **staging location** on each target server (not the live installation path)
  - Applies environment-specific configuration to the staged files (e.g. replaces connection strings, config values from the manifest)
  - Takes a **backup of the current live installation** and the database
  - Verifies the staged files look correct

## Why Stage Before Deploying?

Pre-staging minimises the time during which the application is down. When DEPLOY runs, it can simply swap directories (fast) rather than copying large amounts of data (slow) while services are stopped.

## Artifact Staging Note

The ESP build artifact is currently a **flat folder of DLLs** — not separated per application. Predeploy will need to handle the mapping of DLLs to their correct applications. See [[ESP Known Issues and Risks]].

# Stage 4 — DEPLOY

## Purpose

The actual upgrade — swap the old version for the new version.

## Sequence (High Level)

### 4a. Database

1.  Check `dacpacReady` flag — fail if false
2.  Deploy the dacpac to EspBroker (see [[ESP Database]])

### 4b. Windows Services

1.  Stop all enabled Windows Services (one by one or in parallel — TBC)
2.  For each service:
    a. Move/delete old installation directory
    b. Move staged new files into the installation directory
3.  Apply any final configuration adjustments

### 4c. Citrix Applications

1.  Send notification to active Citrix users (e.g. "System upgrade in 15 mins")
2.  Wait for grace period to expire
3.  Kill any remaining Citrix sessions
4.  Perform Citrix application upgrade (mechanism TBC — believed to be file copy)

### 4d. Start Up

1.  Start all enabled Windows Services
2.  Wait for each to reach Running state before moving on

## Order Matters

The database schema must be deployed **before** starting the new application code, because the new application version expects the new schema. Starting services before the dacpac is deployed would likely cause errors.

## Risk

This is the most **destructive** stage. If something goes wrong mid-deploy, the system may be in a partially upgraded state. This is why rollback planning (currently TBC) is critical. See [[ESP Known Issues and Risks]].

# Stage 5 — POSTDEPLOY

## Purpose

Verify the deployment succeeded and the system is healthy.

## What It Does

### Basic Service Checks

  - Verify all enabled Windows Services are in `Running` state
  - Verify no services crashed immediately after start

### Cycle Checks

  - Extensive checks that exercise the application's functionality
  - Currently heavily reliant on **Citrix UI navigation** — very difficult to automate
  - May initially be a manual prompt ("Please run the cycle checks and confirm pass/fail")
  - Long term: UI automation or API-based checks

## What It Does NOT Do

  - Makes no changes to the system
  - Should be safe to re-run at any time

# Running Subsets of Stages

| Goal                              | Stages to Run                      |
| --------------------------------- | ---------------------------------- |
| Check config before deploying     | `VALIDATE`                         |
| Full pre-flight check             | `VALIDATE,PREREQUISITES`           |
| Stage files only (no deploy yet)  | `VALIDATE,PREREQUISITES,PREDEPLOY` |
| Full deployment                   | All stages                         |
| Re-run health checks after deploy | `POSTDEPLOY`                       |
| Everything except DB              | Custom flags TBC                   |
