Skip to content

Deploying Configurations

This tutorial walks you through the deployment wizard in ntkDeploy. Desktop and dual-platform deployments use six steps; mobile-only deployments use a shorter five-step flow. By the end you will have pushed a configuration artifact to one or more device groups via UNC/SMB or a local path.

Desktop Artifact Format

The editor preview and schema reference still show the underlying appconfig JSON body. For desktop deployment, ntkDeploy encrypts that body into appconfig.ntkd before writing anything to disk.

Desktop appconfig.ntkd uses the same NtkProfileCrypto envelope as mobile .ntkprofile files:

Parameter Value
Format version 0x02
KDF PBKDF2WithHmacSHA256
Iterations 210000
Salt 16 bytes
IV 12 bytes
Cipher AES-256-GCM
Auth tag 128 bits
Password verifier prefix ntk-mobile-profile-v2
Envelope size limit 256 KiB

The deployed desktop payload strips the policy key entirely. When an ABAC path is present, deviceId remains the sole client-side identity reference in the deployed JSON body before encryption.

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

For desktop targets, the preview shows the underlying JSON body only. The deployed file on disk is encrypted appconfig.ntkd, not unencrypted appconfig.json.

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

Review the rollout settings exposed by the wizard.

Option Choices Description
Concurrency 5 / 10 / 25 devices at once Captured by the wizard and shown in the review summary for operator planning.
Retry Count 0 / 1 / 2 / 3 Captured by the wizard and shown in the review summary for operator planning.
Backup Strategy None (overwrite) / Backup before deploy / Rotate backups Captured by the wizard and shown in the review summary. The current deployment service still creates timestamped .bak backups automatically when overwriting an existing artifact.
Stop-on-Error Threshold 0 %–100 % slider Captured by the wizard and shown in the review summary for operator planning.

Click Next after reviewing the options.

Step 4 — Enter Deployment Password

Desktop-targeted deployments now require a password before preflight can complete.

  1. Click Enter Password (or Update Password if you are changing it).
  2. Enter a password with at least 8 characters.
  3. Re-enter it in Confirm Password. The wizard blocks progress until both values match.

Important behavior:

  • ntkDeploy never stores the password.
  • Desktop deployments use this password to encrypt appconfig.ntkd.
  • Both deployments reuse the same password for desktop appconfig.ntkd and mobile .ntkprofile.

Warning: Record the password immediately. There is no recovery path for a lost deployment password; you must rebuild and redeploy the profile with a new password.

Step 5 — 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.

Dual-platform review behavior

If the selected profile targets Both, this step also shows a Mobile Package card with:

  • the mobile payload preview,
  • provider compatibility warnings,
  • the generated profileId,
  • a password summary confirming that the same password will be used for desktop and mobile encryption.

New mobile vaults default to Encryption enabled, so the mobile preview shows encryptionType: "Enabled" unless you explicitly turn it off in the profile editor.

Proceeding to execution

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

Step 6 — 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.

Desktop-managed deployment writes encrypted appconfig.ntkd files to the selected device-group paths. Managed mobile deployment writes {profileId}.ntkprofile under a profiles\ subdirectory.

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 target 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 target path Grant the running user write access to the path. For UNC shares this means SMB share and NTFS permissions; for local paths check folder ACLs.
deploy_write_failed (path not found) Target path does not exist or is inaccessible Verify the path in Device Groups → Paths. For UNC paths confirm the host is online and the share name is correct; for local paths confirm the directory exists.
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 5 blocked) Policy Manager unreachable at deployment time Check the Policy Manager endpoint in Settings. Deployment cannot proceed until the gate is open.

The current rollout implementation records the Retry Count you set in Step 3 and shows it in the review summary, but deployment still performs a single write attempt per target path. If a device fails, fix the underlying issue and re-run the deployment.

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.

Deploying a Mobile Profile

When the selected profile has a Target Platform of Mobile or Both, the deployment flow includes mobile packaging behavior. A Mobile chip next to the profile name in the dropdown indicates a mobile-capable profile.

  • Mobile profiles use a mobile-only flow: Choose Profile → Review Mobile Preview → Enter Profile Password → Select Delivery Method → Execute.
  • Both profiles stay on the standard desktop flow. You still choose device groups, deployment options, and review preflight; the Review step also shows the mobile package preview, and the same deployment password encrypts both artifacts.

Mobile Step A — Review Mobile Preview

After choosing the profile the wizard shows:

  • Mapped vault list — each vault with its ntkMobile provider type (S3, S3_COMPATIBLE, ONEDRIVE, DROPBOX, GDRIVE)
  • Provider compatibility warnings — any NetworkShare providers that were excluded from the mobile build
  • Conductor address — the address that will be embedded in the profile ((none — mobile default will be used) if unconfigured)
  • Validation status — green for valid, red if the payload would fail schema checks
  • Encryption preview — new vaults default to encryptionType: "Enabled" until you disable them in the editor

Mobile Step B — Enter Profile Password

Enter the encryption password for the .ntkprofile file:

  • Minimum 8 characters.
  • Re-enter in the Confirm Password field — both fields must match before Next is enabled.
  • The password is never stored by ntkDeploy.

Warning: Record the password immediately. There is no recovery path — a lost password requires rebuilding the profile with a new password and redistributing to all managed devices.

Mobile Step C — Select Delivery Method

Method When to use
Managed Deploy Target paths in device groups are accessible from this machine (UNC or local). The .ntkprofile is written to {targetPath}\profiles\{profileId}.ntkprofile.
File Export You will distribute the file manually. A Save dialog opens; default filename is {profileId}.ntkprofile.

For Managed Deploy, proceed to the standard device-group selection step. Both UNC paths and local absolute paths are supported.

Mobile encryption time

Because PBKDF2 key derivation uses 210,000 iterations, the encryption step takes approximately 2–5 seconds. The .ntkprofile uses the same NtkProfileCrypto envelope as desktop appconfig.ntkd, so dual-platform deployments pay the encryption cost for both artifacts. A progress indicator is shown — do not close the application during this step.

Mobile rollback

If managed deployment succeeds for some paths but fails for others, ntkDeploy rolls back the partial write: .ntkprofile files written in the current batch are deleted and any previous backups are restored. mobile_profile_rollback_attempted, mobile_profile_rollback_completed, and (on failure) mobile_profile_rollback_failed events are recorded in the audit log for each path where a rollback ran.

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