Deploying

Group Policy

Deploy the deployment MSI with Software Installation and deliver the key with Group Policy Preferences — or a secret-free configuration with a transform and no key at all.

Two recipes. Recipe A deploys the deployment MSI: the package carries the configuration, certificates, secrets and licence keys, and Group Policy delivers the deployment key separately. Recipe B deploys the product MSI with a transform from a transform bundle: no key to deliver, but the configuration may refer to no secrets.

Both use Computer Configuration → Software Installation, both install at boot before anyone signs in, and both need a domain licence key — a machine key licenses one host and every other member would install unlicensed.

Recipe A — the deployment MSI

1. Build and sign

Capture and build the package on your workstation, with your domain key:

dp-deploy build-msi --payload C:\deploy\capture-1 --msi dplens-1.0.912.msi --out C:\bundles\dplens-1 --licence corp.lic

Sign C:\bundles\dplens-1\dplens-1.0.912-deploy.msi with your code-signing certificate. It is built unsigned.

2. Publish the package

Copy the bundle folder to a share readable by Domain Computers — a file server, or \\corp.example\NETLOGON\dplens-1\. The package is safe there: the capture inside it is encrypted, and the key is not in it.

3. Deliver the key

The key must reach each member at %WINDIR%\System32\config\systemprofile\AppData\Local\DPLens\deploy.key — the location the installer reads that is already readable only by SYSTEM and administrators, so a file dropped there inherits the right permissions.

Do not put the key into a Group Policy Preferences Registry item, or into a file under the policy's own SYSVOL folder. Everything in SYSVOL is readable by every authenticated user in the domain; the key would be too.

Use Computer Configuration → Preferences → Windows Settings → Files:

The file arrives owned by SYSTEM, in a folder only SYSTEM and administrators can read; the installer accepts exactly that. Because the installer deletes the key after use, Create (not Replace) is right: the item recreates the file only when it is absent, which is also what makes a future re-push or upgrade possible.

Alternatively, a computer startup script that reads the key from the same restricted share and stages it:

Get-Content \\server\dplens-keys$\bundle-1\deploy.key | powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass `
    -File \\server\dplens\bundle-1\Stage-DeployKey.ps1 -Target SystemProfile

4. Assign the package

Group Policy Management → the GPO linked to the target computers → Computer Configuration → Policies → Software Settings → Software installation → right-click → New → Package:

  1. Pick \\<share>\dplens-1\dplens-1.0.912-deploy.msi (the UNC path, never a mapped drive).
  2. Deployment method Assigned. No transform is needed — the package carries everything.
  3. Leave Uninstall this application when it falls out of the scope of management off unless you want a GPO unlink to remove the agent (it keeps ProgramData\DPLens).

5. What happens on the member

At the next boot Windows Installer installs the package: the installer finds the key in the system profile, opens the capture, writes the configuration, certificates and secrets, keeps the licence key that binds the member, deletes the key file, and starts the service.

Confirm the ordering on a pilot member before rolling out. Group Policy processes Software Installation and Preferences during the same boot, and the key must be there when the installer runs. If on your domain the first boot installs before the file arrives, the install fails with no deployment key was found in the member's System log and is retried at the next boot, by which time the key is present. If that extra reboot is not acceptable, deliver the key one boot ahead: link the Preferences item first, the Software Installation package at the next change.

Verify on the member:

Get-Service dplens                                                       # Running
Get-Content C:\ProgramData\DPLens\state\deploy.json                      # names your bundle
Test-Path $env:WINDIR\System32\config\systemprofile\AppData\Local\DPLens\deploy.key   # False — consumed
& "C:\Program Files\DPLens\dplens.exe" --verify-licence C:\ProgramData\DPLens\config\licence.key

6. Updating the fleet

Build a new bundle from a new capture (or a new product MSI), put it on the share with a new key file beside the old one, and in the GPO add the new package with Upgrades pointing at the old one, or redeploy. A newer package over an installed member applies the new capture and keeps its working licence.

For a configuration change without a version change, push the new bundle instead — Software Installation reinstalls a package only when its product version changes.

Recipe B — the transform bundle (no secrets)

Use this when your configuration refers to no secrets: a syslog-over-TLS configuration with server-certificate validation and no console password, say. Group Policy installs the product MSI with the bundle's transform, and nothing else has to run on the machine.

1. Build the bundle

dp-deploy bundle --config wel-syslog-tls.yaml --msi dplens-1.0.912.msi --out C:\bundles\dplens-42 `
    --licence corp.lic --console off --epoch 42 --no-script
dp-deploy verify C:\bundles\dplens-42

The licence should be a domain key; dp-deploy prints which kind it is. A configuration that references a secret is refused with --no-script; use Recipe A for it.

2. Publish it

Copy the folder to a share readable by Domain Computers — SYSVOL/NETLOGON (\\corp.example\NETLOGON\dplens-42\) or a file server. The MSI reads the package and the transform as the machine account; nothing here needs to be writable, and nothing here is secret.

3. Create the package

Computer Configuration → Policies → Software Settings → Software installation → right-click → New → Package.

  1. Pick \\<share>\dplens-42\dplens-1.0.912.msi (use the UNC path, never a mapped drive).
  2. Choose Advanced (not Assigned): the transform can only be attached at creation.
  3. Modifications tab → Add → \\<share>\dplens-42\dplens.mst → OK. Do not open the Deployment tab first and press OK — a package created without its transform installs the default document and must be removed and re-created.
  4. Deployment type Assigned; leave Uninstall this application when it falls out of the scope of management off unless you want a GPO unlink to remove the agent (it keeps ProgramData\DPLens).

4. What happens on the member

At the next boot Windows Installer installs the package with the transform: the installer validates the embedded document, verifies the licence against that host (signature, expiry, binding), provisions the service identity, installs ProgramData\DPLens\config\agent.yaml and licence.key, and starts the service. With --console off there is no console process at all.

Verify on the member:

Get-Service dplens                                   # Running
Get-Content C:\ProgramData\DPLens\config\agent.yaml  # the same file the bundle carries
& "C:\Program Files\DPLens\dplens.exe" --verify-licence C:\ProgramData\DPLens\config\licence.key

5. Upgrades

Build a new bundle (new --epoch) from the new MSI — the transform is tied to the MSI's product code — put it on the share and, in the GPO, right-click the old package → All Tasks → Redeploy application, or add the new package with Upgrades pointing at the old one.

When it fails

The install fails loudly rather than installing something wrong. Look in:

Any tool that can run msiexec deploys the same packages — see Intune, Configuration Manager, RMM and cloud images.