Frequently Asked Questions¶

Answers to the most common questions about ntkDeploy. Jump to the section that matches your question, or use your browser's Find function (Ctrl+F) to search.

Prerequisites¶

No prior knowledge required. For deeper context on any topic, follow the links inside each answer to the relevant guide pages.

General¶

What is ntkDeploy / ntkDrive?¶

ntkDrive is a Windows fleet-management agent that reads a JSON configuration payload from a UNC/SMB share and applies it to the local machine. ntkDeploy is the administrator tool used to author, version, and publish those configuration profiles to the network shares that ntkDrive reads.

In practice: you create profiles in ntkDeploy, assign them to device groups, run the Deployment Wizard to write the JSON payloads to the share, and ntkDrive on each managed device picks up the new configuration on its next poll cycle.

Is data stored in the cloud?¶

No. All profile, device group, policy, and audit data is stored in a local SQLite database (app.db) on the machine running ntkDeploy. There is no cloud sync and no external data dependency for the core workflow. The only external connection is to the optional policy server (ntkDrive conductor) for ABAC enforcement.

See Architecture Overview for more detail.

How does the environment filter work?¶

ntkDeploy uses a free-form environment label on every profile to allow you to organise profiles by lifecycle stage, department, or purpose. Common labels include Development, Staging, and Production, but you can create any label you need. The active environment is shown in the left sidebar and acts as a filter for the profile list.

Switching environments (clicking a row in the environment sidebar) instantly filters the profile list to show only profiles with that label. No data from other environment labels is affected.

Profiles can be moved to another environment by cloning the profile and changing the Environment field on the clone. See Environments.

What does the audit log track?¶

The Audit Log records every significant action taken in ntkDeploy. Recorded event types include:

Category	Example events
Profile lifecycle	`profile_created`, `profile_updated`, `profile_priority_changed`
Deployment	`assignment_created`, `rollout_succeeded`, `rollout_failed` (with backup path)
Policy telemetry	`policy_capabilities_check`, `policy_connectivity_gate` (failure and error outcomes only)

Each entry includes a UTC timestamp, the actor identity, the affected entity ID, and a details payload with context about the action.

See Audit Log Reference.

ntkDeploy is a single-user desktop application. The SQLite database is held locally and is not designed for concurrent multi-user access. Multi-admin coordination is handled through environment promotion: one admin manages profiles in the Development environment, promotes them to Staging for validation, and finally to Production for deployment.

See Environments for the promotion model.

How do I upgrade to a new version?¶

Install the updated MSIX package using the same installation script:

Set-ExecutionPolicy Bypass -Scope Process
.\scripts\install_msix_trust_and_app.ps1

Your local SQLite database is preserved and migrated automatically. The app runs schema migrations on startup — you do not need to export or reimport data.

See Installation for the full installation procedure.

What Windows versions are supported?¶

ntkDeploy primarily targets Windows 10 (build 19041 / version 2004 and later) and Windows 11. Older Windows versions are not supported. Run winver to check your build number.

UNC/SMB connectivity features require Windows networking with SMB 2.0 or later. SMB 1.0 is not required.

Can I run ntkDeploy on macOS or Linux?¶

ntkDeploy is Windows desktop-first. Flutter project files for macOS, iOS, Android, and Web are present in the repository but those builds are not supported for production use. UNC path validation explicitly returns a failure on non-Windows platforms.

How do I back up my configuration data?¶

Copy the SQLite database file from:

%APPDATA%\com.jibberishdev.ntk_deploy\app.db

to a safe location. This single file contains all profiles, device groups, assignments, global settings, and the audit log. Restore it by placing the backup copy back at the same path before launching ntkDeploy.

For individual profiles you can also use Profiles → Export to export a JSON file that can be imported on any ntkDeploy installation — see Importing and Exporting Profiles.

Where are deployment artifacts stored?¶

Built JSON payloads and deployment metadata are stored locally in the artifacts directory. The default location is determined by the application's data path; you can override it under Settings → Artifacts → Artifacts directory.

Artifacts older than the configured retention period (default: 30 days) are eligible for automatic cleanup via Settings → Artifacts → Clean up old artifacts.

See Settings Reference → Artifacts.

Can I automate deployments via CLI or scripts?¶

There is no built-in CLI in the current release. Deployments are triggered through the Deployment Wizard in the UI. Automation is on the roadmap; for now, administrators perform deployments interactively and rely on the Audit Log for a traceable record.

Profiles¶

What profile schema versions are supported?¶

The current release supports schema version v1.0. The schema is registered in the schema registry and controls the form fields available in the profile editor. All five steps of the schema validation pipeline validate against this schema.

See Profile Schemas Reference.

How many profiles can I have?¶

There is no enforced limit. Profiles are stored in SQLite and filtered by environment. Very large profile counts (thousands) will not degrade core functionality, but the profile list view does not currently paginate — extremely long lists may scroll slowly.

What happens to existing profiles when I upgrade?¶

Profile data is preserved. Schema migrations are applied automatically on startup. If a migration encounters a problem, the audit log records the failure and an error banner is shown on the Dashboard — see Common Issues → Database Locked or Corrupted.

Deployments¶

What happens to the existing config file when I deploy a new version?¶

Before overwriting, DeploymentService creates a timestamped backup alongside the original file:

\\server\share\configs\ntk.json.bak.2026-03-03T14-22-10.000000

This backup is recorded in the rollout_succeeded audit log entry under backupPath. If the deployment fails and you need to roll back, copy the .bak.* file back to the original name — see Deployment Failures → Rollback Guidance.

What does "Deployment Wizard" do exactly?¶

The Deployment Wizard is a multi-step guided flow that: 1. Validates all selected profile versions against the schema pipeline. 2. Evaluates the Policy Connectivity Gate (if policy enforcement is enabled). 3. Runs per-device ABAC preflight checks. 4. Writes the built JSON payload to each target UNC path. 5. Records the result (success or failure, including backup path) in the Audit Log.

See Deploying Configurations and Deployment Preflight Reference.

What are preflight checks and can I skip them?¶

Preflight checks are automated validations that run before payload files are written to the network shares. They guard against writing broken or unauthorized configurations:

Check	What it validates
Schema validation	All profile fields satisfy the `v1.0` schema rules
Policy Connectivity Gate	The policy server is reachable (if ABAC is enabled)
Per-device ABAC	Each device's attribute assignments satisfy active policy rules
UNC path reachability	Each target share is accessible with write permission

You cannot skip preflight checks in the current release. They are executed automatically by the Deployment Wizard for every rollout. If a check fails the wizard shows the failing gate code and blocks the write step — fix the underlying issue and retry. This ensures every deployed configuration is valid and authorised.

See Deployment Preflight Reference.

Can I deploy to devices not in a group?¶

No. The Deployment Wizard operates on assignments — a pairing of a profile version with a device group. A device must be a member of at least one device group, and that group must have a UNC target path configured, before it can receive a deployed configuration.

To deploy to a standalone device, create a device group containing only that device, add the appropriate UNC path, and assign the desired profile to it. See Managing Device Groups.

Can I deploy to multiple device groups at once?¶

Yes. The Deployment Wizard allows you to select one or more device groups before proceeding (Step 2). The Concurrency option in Step 3 controls how many device targets are written in parallel within the rollout — set it lower on fragile or high-latency networks, and higher when the network is reliable and you want faster completion.

See Deploying Configurations — Step 3.

People & Assignments¶

How do I add a new person?¶

Open Policy in the left sidebar.
Click the People tab, then click Add Person in the toolbar.
Fill in the required fields: Display name and optionally Org Unique ID, Tags, and Status.
Click Save. The new person record appears in the list and becomes available in the person-picker when assigning ownership to devices in device groups.

People records are shared across all environment labels — a person created once is available when assigning ownership or managing policies regardless of which profile environment is active.

See Managing Policies → Adding a person.

Policy & ABAC¶

What is ABAC and do I need it?¶

Attribute-Based Access Control (ABAC) is an optional policy enforcement layer that links device configurations to verified user or device attributes stored on a policy server. You only need it if your ntkDrive deployment requires policy-gated attribute assignments. If your profiles contain no ABAC fields, the policy connectivity gate and per-device preflight steps are skipped entirely.

See Managing Policies and Deployment Preflight Reference.

What is the Policy Connectivity Gate?¶

The Policy Connectivity Gate is a fail-closed circuit breaker that opens when the policy server is confirmed reachable and closes automatically when it becomes unreachable. A closed gate blocks all policy-dependent deployments with the code policy_connectivity_gate_closed. The gate reopens automatically once background monitoring confirms connectivity and capability checks pass — no restart is required for normal recovery.

See Deployment Failures → Policy Connectivity Gate and Settings Reference → Policy Server.

How do I test my policy server connection?¶

Go to Settings → Policy Server and click Test connection. The result is shown in a snack bar: - Policy server connection succeeded. — endpoint is reachable with the configured TLS credentials. - An error message — fix the certificate paths or URL and retry.

Note that a passing test connection does not directly re-open the Policy Connectivity Gate; the gate is managed by the background monitoring service and will reopen automatically once checks pass. If the gate does not recover on its own, restarting ntkDeploy is a valid troubleshooting step to reset gate state.

UNC Paths & Network¶

How do I test if a UNC path is reachable before adding it to a device group?¶

From PowerShell:

# Reachability
Test-Path "\\\\fileserver01\\ntkdrive$\\configs"

# Write permission
$f = "\\\\fileserver01\\ntkdrive$\\configs\\test_$(Get-Random).tmp"
Set-Content $f 'test'; Remove-Item $f

# SMB port
Test-NetConnection -ComputerName fileserver01 -Port 445

If all three succeed, ntkDeploy's preflight checks will also pass for that path.

See Connectivity Issues for the full diagnostic guide.

Can I use IP addresses instead of hostnames in UNC paths?¶

Yes. ntkDeploy validates the UNC path format and does not require the server segment to be a hostname. IP addresses are valid:

\\10.0.1.50\ntkdrive$\configs

Note that Kerberos authentication requires a valid hostname and SPN — if your environment uses Kerberos, use the FQDN rather than the IP address.