Deploy and Roll Out PTC

Deployment Sequence

Deploy PTC in the following order. Enabling interception before Artifactory and workstation trust are ready can break package installs.

flowchart LR
    Step1["1. Configure JFrog Artifactory\n(repos, Package Reroute API,\nanonymous access, redirect)"]
    Step2["2. Install Zscaler CA\nand trust configuration\non workstations"]
    Step3["3. New terminal sessions\n/ IDE restart\n(pick up env vars)"]
    Step4["4. Activate ZIA rules\n(URL category, SSL inspection,\nredirect rule)"]

    Step1 --> Step2 --> Step3 --> Step4

Required Order of Operations

To deploy PTC in the required order:

1. Configure JFrog Artifactory: Create a remote repository for each ecosystem, then complete Step 2: Register repositories with Package Reroute using Update Registry Configuration (PUT /artifactory/api/package-reroute/config/{type}) for each package type. PTC does not work without this API request. The repo_key must be a remote repository. Configure anonymous access and verify /package-reroute as described in Configure Artifactory for PTC. Artifactory must be ready before ZIA redirects traffic. Otherwise, installs fail after interception starts.
2. Set up Zscaler CA and application trust on developer workstations for each client and OS in scope. MDM is optional. Use your endpoint deployment approach. Follow Installation Script and Zscaler trust-store guidance. Trust must be in place before SSL inspection is enabled.
3. Ask developers to open new terminal sessions or restart IDEs after certificate and environment-variable changes. Most client-specific environment variables are read when a new shell starts, and existing shells keep the old environment.
4. Configure and activate the ZIA rules (URL category, SSL inspection rule, URL filtering/redirect rule). Enable interception only after Artifactory and workstation trust are fully ready.

Warning: If ZIA rules are activated before Artifactory is configured or before certificate trust works for your package clients, installs can fail with SSL errors or HTTP errors. New terminal sessions or an IDE restart are usually required after env updates.

Gradual Rollout Recommendation

To reduce risk, deploy PTC gradually rather than to the entire organization at once. Phase by audience (pilot groups first) and by package ecosystem (for example npm first, then PyPI, then Docker/OCI) so each path can be validated before wider rollout.

Gradual Rollout Readiness Before ZIA Activation

The Deployment Sequence still applies during phased rollout. Prepare endpoints first, then enable interception for the same cohort.

Practical pattern:

• Start with a pilot group and a single ecosystem (commonly npm).
• Confirm trust and successful installs before enabling redirect rules for additional users.
• Expand in controlled waves using ZIA Groups.
• Add additional registry domains only after endpoint trust and smoke tests are complete for that stack.

Why Gradual Rollout Is Important

Rolling out every user and every package client at the same time carries risk:

• Endpoint trust or environment gaps may affect only specific client stacks.
• Existing network and security policies can behave differently across teams.
• A phased rollout reduces blast radius and shortens troubleshooting cycles.
• Different package managers have different TLS and client behaviors.

A phased approach by audience, by registry domains in ZIA, and by configured ecosystems in Artifactory lets you identify and resolve issues with minimal disruption.

Recommended Rollout Phases

Phasing by package type (optional): Within any phase above, you can keep ZIA’s custom URL category minimal (e.g., only registry.npmjs.org until npm is stable), then add domains for PyPI, container registries, Hugging Face, and so on as you validate each stack. Align Artifactory Package Reroute repo_key settings so only ecosystems you intend to govern are in the path. This is independent of JFrog vs. Zscaler ownership: Zscaler controls which hostnames are intercepted; JFrog controls which repository serves each type.

What to Monitor at Each Phase

• Package installs succeed without SSL errors
• Download and install time stays acceptable for your teams (throughput may differ from a direct path to the public registry—for example on first fetch, cache miss, or extra redirect hops—so compare against your own baseline and adjust capacity or caching if installs feel too slow)
• Packages appear in Artifactory's cached artifacts
• Curation audit log shows expected entries (only if JFrog Curation is enabled on the resolving remotes)
• Artifactory system logs show package reroute lines (user, original and target URLs, registry type, user agent)—see Package reroute logs (Artifactory)
• npm audit and other POST-based commands continue to work normally
• Lock file behavior is acceptable (see Lock File Considerations for npm. Minor URL differences are expected and not a blocking issue.)
• No unexpected workstation or application breakage from the installation script
• When you add another registry domain or package client to the rollout, re-run targeted smoke tests for that client (install, lock files, TLS) before expanding scope further

You can use the following command during pilot verification to confirm package installation behavior from a workstation:

npm install <PACKAGE_NAME> --loglevel verbose

Where:

• <PACKAGE_NAME> is the public package name used for your pilot smoke test.

For example:

npm install express --loglevel verbose

Consumption Impact for SaaS Customers

If your JFrog Artifactory instance is a SaaS (cloud-hosted) subscription, be aware that deploying PTC will affect your consumption metrics.

How Consumption Is Affected

When PTC is active, all developer workstations that install packages through the redirected flow will generate traffic against your JFrog Artifactory instance. This means:

• Every package download that was previously going directly to the public registry will now be routed through and served by your Artifactory instance.
• Each workstation added to the PTC deployment increases the total volume of requests and data transfer against your Artifactory subscription.
• Cached packages reduce repeated upstream fetches, but the initial download of each package version will count toward consumption.

Recommendation

Before deploying PTC across your organization, review your current SaaS subscription limits and projected consumption increase with your JFrog account team. The gradual rollout approach (see Gradual Rollout Recommendation) also helps you monitor consumption growth incrementally rather than experiencing a sudden spike.

Frequently Asked Questions

This section provides answers to frequently asked questions about deploying Package Traffic Controller (PTC).

Related Topics

• Package Traffic Controller (PTC) overview
• Prerequisites and Installation Script
• Configure Artifactory for PTC