Configure Workstation for PTC

Workstation Configuration for PTC

PTC redirected traffic is SSL-inspected by your SASE before it reaches Artifactory. For a developer workstation to participate in PTC, every package client (npm, pip, Docker, and so on) on that workstation must trust the SASE root CA — typically through OS trust stores, application-specific trust stores, or environment variables.

This page covers the workstation-side setup: which scripts to use, the minimum certificate and environment variable expectations, and where to look for client-by-client and OS-by-OS detail. SASE provider and Artifactory-side setup is covered in your SASE provider's guide (see Supported Security Edges) and Configure Artifactory for PTC.

Run workstation configuration before activating SASE redirect rules that intercept registry traffic — see Deployment Sequence. Trust must be in place before SSL inspection is enabled, otherwise installs break with TLS errors.

Installation Script

Important: This is not JFrog-specific. The certificate installation described in this section is a general requirement for SASE SSL inspection to work properly on any workstation. Any application or CLI tool that makes HTTPS calls through a SASE-inspected network must trust the SASE root CA certificate. This applies regardless of whether JFrog Artifactory or PTC is involved. For an authoritative reference on SSL inspection certificate deployment, see your SASE vendor's documentation (for example, Zscaler's Adding Custom Certificate to an Application-Specific Trust Store).
PTC relies on workstation certificate installation you deploy with the approach that fits your organization (MDM is not required—endpoint management, imaging, scripts, or manual steps are all valid). The scripts extract or reference the SASE CA and set environment variables so Node.js (npm and related clients) and Python/pip trust TLS through SSL inspection, as an example.

Installation scripts may require customer-specific adjustments. Every organization's endpoint configuration, certificate chain, MDM tooling, and security policies differ. Review and adapt scripts to your environment before broad rollout.
This product documentation does not duplicate the script README. For authoritative detail, use:

• Repository root overview: README.md (links to the script guide)
• Scripts and full documentation: scripts/README.md in the package-reroute repository.

That README includes: supported OSes, package clients (npm, pnpm, yarn via Node; pip/pipenv/uv with validation notes), environment variables with version applicability, flowchart, test coverage, MDM validation on Action1 (other MDMs may need adjustment), which clients require env-based configuration (typically older npm/Python) vs. which may not need extra environment variables when the OS trust store is sufficient, and the minimum variables needed if you implement the same behavior without the scripts.

For example, you can validate the certificate path used by client tooling:

openssl x509 -in "<SASE_CA_PATH>" -noout -issuer

Where:

• <SASE_CA_PATH> is the full path to the SASE CA certificate file used by your package client.

For example:

openssl x509 -in "/opt/certs/sase-ca.pem" -noout -issuer

At a Glance

Run the installation before SASE redirect rules that intercept registry traffic are activated (see Deployment Sequence).

Containers and Virtual Environments

This section covers workstation-side trust configuration when developers work inside Docker containers or Python virtual environments. SASE SSL inspection happens on the host, but containers and isolated environments do not automatically inherit the host's CA trust — so they need their own configuration. Supported Docker scopes match the supported client matrix in Docker, Hugging Face, and other types; Podman and other engines are out of scope unless JFrog announces support separately.

Docker containers do not automatically inherit the SASE CA certificate from the host workstation. When a container runs npm install (or any package install) and the traffic is intercepted by your SASE via the host's SASE client, the container will encounter SSL errors because it does not trust the SASE certificate.

The certificate must be explicitly added to the container image. You can do this by either baking the CA into the image at build time (e.g., COPY a PEM file and set NODE_EXTRA_CA_CERTS, or install it into the OS trust store) or by mounting the certificate at runtime with matching environment variables.

Note: This is a well-known requirement for any corporate TLS-inspecting proxy, and Docker documents this use case directly. See Docker’s official guide Using Docker with Zscaler for detailed instructions on adding custom CA certificates to images, build contexts, and related configuration so that containers — not only the host — trust inspected traffic.
The patterns below are consistent with Docker’s documentation and tailored specifically for PTC (npm/Node and general OS trust).

Docker Configuration for npm (Node.js)

To ensure a Docker container running npm successfully works with the PTC rerouting solution, add the following to your Dockerfile:

Example Dockerfile:

FROM node:20
COPY sase-ca.pem /sase-ca.pem
ENV NODE_EXTRA_CA_CERTS=/sase-ca.pem
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "index.js"]

Where:

• sase-ca.pem: PEM file for the SASE root CA (same file used on the host workstation)

The sase-ca.pem file must be present in the Docker build context (the same directory as the Dockerfile, or accessible via a path). This is the same PEM file used by the installation script on the host workstation.

Using docker run:

If you prefer to mount the certificate at runtime instead of baking it into the image, you can pass it as a volume mount and environment variable:

docker run \
  -v /opt/certs/package-route.pem:/sase-ca.pem:ro \
  -e NODE_EXTRA_CA_CERTS=/sase-ca.pem \
  your-image

Using docker-compose:

services:
  app:
    image: your-image
    volumes:
      - /opt/certs/package-route.pem:/sase-ca.pem:ro
    environment:
      - NODE_EXTRA_CA_CERTS=/sase-ca.pem

General Container Certificate Installation

For containers that need to trust the SASE certificate at the OS level (not just for Node.js), copy the certificate into the container's system trust store and update it:

FROM debian:bookworm
COPY sase-ca.pem /usr/local/share/ca-certificates/sase-ca.crt
RUN apt-get update && \
    apt-get install -y ca-certificates && \
    update-ca-certificates

This approach is necessary for tools that rely on the system trust store rather than application-specific environment variables (e.g., curl, wget, Python requests without REQUESTS_CA_BUNDLE).

For multi-stage builds, ensure the certificate installation occurs in the final stage so it is present in the runtime image.

See again Using Docker with Zscaler for Docker’s full walkthrough (image CA installation, build context, and product-specific notes). Note: Containers that are already running generally still need the certificate and any required environment variables inside the container namespace; injecting trust only on the host is often insufficient for TLS from within the container. This guide focuses on build-time COPY / RUN update-ca-certificates and explicit runtime volume and environment-variable patterns.

For enterprise proxy and certificate topics beyond Zscaler, refer to Docker’s documentation for your edition (Engine / Desktop) as it applies to your environment.

Python Virtual Environments

Python virtual environments (venv, virtualenv) on the host workstation inherit the host's environment variables, including REQUESTS_CA_BUNDLE. If the installation script has already configured REQUESTS_CA_BUNDLE in the user's shell profile, pip installs inside virtual environments should work without additional configuration.

Some newer Python builds on macOS and Windows can use the operating system trust store for TLS; in those cases pip may work without REQUESTS_CA_BUNDLE. See scripts/README.md in the PTC repository for version-oriented guidance; always validate in your own image or pilot.

If pip installs inside a virtual environment fail with SSL errors, verify that the REQUESTS_CA_BUNDLE environment variable is set and points to a valid PEM file:

echo $REQUESTS_CA_BUNDLE
openssl x509 -in "$REQUESTS_CA_BUNDLE" -noout -issuer

Frequently Asked Questions

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

Related Topics

• Package Traffic Controller (PTC) overview
• Review PTC Prerequisites
• Deploy and Roll Out PTC
• Supported Security Edges