Skip to content

Deploying Configurations

This tutorial walks you through the full five-step deployment wizard in ntkDeploy. By the end you will have pushed a configuration artifact to one or more device groups via UNC/SMB.

Prerequisites

Before opening the wizard, confirm the following are all in place:

Opening the wizard

Select Deploy from the sidebar navigation. The wizard loads automatically. If data fails to load you will see an error message with a Retry button — check your network connection and retry.

Step 1 — Choose Profile

The first step shows a Profile dropdown listing every profile in your local database.

  1. Click the dropdown and select the profile you want to deploy. Each entry shows a status icon:
  2. Check circle (green) — the active version is valid and ready to deploy.
  3. Warning (amber) — the active version is draft; deployment may proceed but the configuration has not been fully validated.
  4. Error (red) — the active version has validation errors. A banner beneath the dropdown will read "This profile has validation errors. Deployment may fail." Resolve errors in the profile editor before continuing.
  5. After selecting a profile, a Profile Details card appears showing the environment label, optional department, and priority. Expand the Settings Preview tile to inspect the raw JSON.
  6. Click Next when satisfied.

Tip: Only profiles whose active version is valid should be deployed to production device groups. Use draft-status profiles in development environments only.

Step 2 — Choose Device Groups

This step shows a checkbox list of every device group available.

  1. Check one or more device groups to include in the rollout. Each entry shows the group name and the number of device paths it contains.
  2. A Total devices selected card appears and updates dynamically as you check and uncheck groups.
  3. Click Next when your target groups are selected.

Note: You cannot proceed with zero groups selected. If no groups appear, navigate to the Device Groups section and create or import one — see Managing Device Groups.

Step 3 — Deployment Options

Configure how the rollout behaves.

Option Choices Description
Concurrency 5 / 10 / 25 devices at once Number of device targets processed in parallel. Reduce for fragile networks.
Retry Count 0 / 1 / 2 / 3 How many times to retry a failed device write before recording it as failed.
Backup Strategy None (overwrite) / Backup before deploy / Rotate backups Backup before deploy creates a timestamped .bak file next to the existing config before overwriting it. Rotate backups keeps a rotating set. Choose None only if disk space is critical.
Stop-on-Error Threshold 0 %–100 % slider If the proportion of failed devices exceeds this threshold during a rollout, the deployment is halted automatically. Set to 0 % to halt on the first failure; set to 100 % to continue regardless of failures.

Click Next after reviewing the options.

Step 4 — Review (Preflight)

This is the most important step. As soon as you arrive here, ntkDeploy automatically runs the preflight sequence:

  1. Connectivity gate check — verifies the Policy Manager /capabilities and /readyz endpoints respond successfully.
  2. Ownership mapping check — confirms that every device key in the selected groups has an ownership mapping to a Peer ID.
  3. Policy plan check — calls the Policy Manager to obtain a deployment plan for the selected devices; identifies blocking and warning findings.
  4. Snapshot retrieval — captures a deterministic snapshot reference to embed in the artifact.

While the checks run, the Deploy button reads Checking Preflight… and cannot be clicked.

Reading the preflight summary

A Policy Preflight Summary card appears when the check completes:

  • Blocking findings: N — if N > 0, deployment is blocked. Each blocking finding shows the affected Peer ID and a message explaining why.
  • Warning findings: N — warnings do not block deployment but should be reviewed.
  • Actions to create: N — the number of policy actions the wizard will create automatically on deployment.

Resolving a blocked preflight

Device ownership not assigned (device_owner_unassigned)

If any device has no owner, a Deployment blocked banner appears and a remediation card offers two options:

  • Go to Device Group to assign people — opens the Device Group detail page so you can assign owners one at a time inline. When you navigate back, the wizard re-runs preflight automatically.
  • Assign People (bulk) — opens an Assign People (bulk) dialog with a person picker. Select a person and click Assign. The wizard assigns that person as owner for every unmapped device in the selected groups, then re-runs preflight automatically.

Connectivity gate failed

If the connectivity gate is closed:

  1. Open Settings from the sidebar.
  2. Verify the Policy Manager endpoint URL is correct and the server is reachable from this machine.
  3. Click Validate in Settings. When the badge turns healthy, return to the wizard and re-run preflight.

Blocking policy findings

If the Policy Manager returns blocking findings, review each one:

  1. The message identifies the Peer ID and the reason (for example, a missing required attribute or an expired certificate).
  2. Navigate to Policy → Attributes and ensure the required attributes exist and are assigned to the affected people.
  3. Return to the wizard; the Review step re-runs preflight on arrival.

Credential-bearing provider warning

If the selected profile references a credential-bearing provider (Amazon S3, MinIO, Wasabi, or iDrive E2), a warning banner reads:

"Credential-bearing provider settings will be embedded in deployment payloads."

Review the listed provider types. If you intend to redact credentials from artifacts, edit the profile sources before deploying.

Confirming a missing-plan deployment

In some Policy Manager configurations the plan check returns a missing-plan status for certain devices. When this occurs the Deploy button changes to Confirm and Deploy. Clicking it acknowledges the missing-plan condition and proceeds.

Proceeding to execution

When all blocking findings are resolved and preflight returns a clean result, click Deploy.

Step 5 — Execute

The wizard advances to the Execute step automatically when preflight is verified. Deployment starts immediately with no additional confirmation required.

While deploying, a spinner and the message "Deploying…" and "Please wait while files are copied to device groups." are shown. Do not close the application during this step.

Successful deployment

When all devices are processed successfully, the step shows:

  • A Deployment Complete! heading with a green check icon.
  • A Summary card listing:
  • Number of device groups processed.
  • Total devices that succeeded.
  • Total devices that failed (shown in red, if any). See Handling partial failures below.

Click Done to return to the Audit Log, where the full deployment record is stored.

Handling partial failures

A deployment is considered partial when some devices succeed and others fail. This is normal in large fleets where individual machines may be offline or their UNC path inaccessible.

To identify failed devices:

  1. Click Done to go to the Audit Log.
  2. Locate the most recent assignment entry and expand it to see per-device rollout events.
  3. Each failed event shows the target path and the error message (for example, deploy_write_failed: Access denied).

Common failure causes and remediation

Error code Cause Fix
deploy_write_failed No write permission on the UNC share Grant the running user write access to the share, or use a service account with sufficient privileges.
deploy_write_failed (path not found) UNC path does not exist or host is offline Verify the path in Device Groups → Paths. Confirm the machine is online and the share name is correct.
backup_not_found Restore from backup was requested but the backup file is missing Re-deploy without restoring. If the original config is critical, recreate it manually.
Connectivity gate failure (step 4 blocked) Policy Manager unreachable at deployment time Check the Policy Manager endpoint in Settings. Deployment cannot proceed until the gate is open.

Failed devices are automatically retried up to the Retry Count you set in Step 3. Devices that exceed the retry count are recorded as failed in the rollout event.

Deployment failed (all devices)

If every device fails, the step shows a Deployment Failed heading and an Error Details card with the raw error message. This indicates a systemic problem (for example, no network path to the share, or an invalid artifact). Review the error and correct the underlying issue before re-running the wizard.

Reviewing deployment history

All deployments are recorded in the Audit Log, regardless of outcome. Navigate to Audit Log from the sidebar to:

  • Search by profile name, device group, or timestamp.
  • Inspect every rollout event per device.
  • Identify patterns across repeated deployments.

See Audit Log reference for details.

Next Steps