Custom Upstream Registries
An upstream is the registry ShieldedStack uses to serve package-manager requests and deliver artifacts. Developers still point their package managers at the ShieldedStack proxy endpoints; operators choose the upstream through application configuration, not the Portal. ShieldedStack’s own metadata enrichment uses public registries, independently of that delivery choice.
Package manager → ShieldedStack → configured public-package mirrorSource selection is deployment-wide, shared by every tenant and workspace. Workspace package policies still decide whether an artifact may be downloaded. Apply identical source definitions and credentials to the Portal, worker, and proxy. Use the same ShieldedStack release for all service images.
Supported sources and limits
Section titled “Supported sources and limits”| Source key | Registry entry point | How it is used |
|---|---|---|
npm |
The registry URL used in .npmrc, including any mount prefix. |
Metadata and tarball URLs are resolved within that registry mount. |
nuget |
The NuGet V3 service-index URL used in NuGet.Config. |
The index supplies registration metadata and package-content endpoints. Do not supply those resource URLs instead of the index. |
cargo |
A sparse-index URL, with sparse+https://…/ or https://…/. |
The index’s config.json supplies the download template. Git indexes are not supported. |
pypi |
The Simple API entry point used as pip’s index-url, including /simple/ or /+simple/ when present. |
HTML and JSON file links are rewritten; standard Simple entry points also permit sibling artifact directories within that repository. |
maven |
The repository root used by Maven or Gradle, including its mount path (for example /repository/maven-public/). |
Artifact coordinates are appended below this root. |
go |
The module proxy root used in GOPROXY. |
Module protocol paths, including escaped module names, are preserved. |
pub |
The hosted Pub repository root used in PUB_HOSTED_URL. |
Package/version protocol responses resolve archive URLs after policy permits a download. The ShieldedStack client endpoint remains /dart/. |
rubygems |
The source root used by RubyGems or Bundler. | Compact indexes, specifications, and gem downloads stay under this root. |
composer |
The Composer repository root containing packages.json, not its /p2/ path. |
Composer 2 metadata-url discovery and inline package repositories are supported; archives are re-resolved from that repository after policy allows them. |
hex |
The Hex repository root, not the Hex enrichment API. | Signed repository records and tarball downloads are forwarded without modifying their contents. |
There is one configured source per protocol, not a source list or a private/public fallback chain. Omitted entries keep their public defaults. If a configured registry is unavailable, ShieldedStack does not switch delivery to the public registry. Container registries use separate OCI_<REGISTRY>_* settings.
An override changes proxy delivery and protocol discovery, not enrichment. The proxy may read a NuGet service index, Cargo bootstrap/checksum records, Composer repository metadata, or Pub version/archive records, and forward package-manager metadata requests to the configured registry. Those protocol reads are not sources of enrichment facts: all ten ecosystems continue to use their canonical public enrichment sources, without the mirror’s credentials.
Application settings
Section titled “Application settings”Replace <source> with npm, nuget, cargo, pypi, maven, go, pub, rubygems, composer, or hex:
| Environment variable | Meaning |
|---|---|
PackageUpstreams__<source>__Url |
Required when overriding that source. Absolute registry URL, without embedded credentials, query, or fragment. |
PackageUpstreams__<source>__Token |
Optional Bearer token. Do not also set username/password. |
PackageUpstreams__<source>__Username and PackageUpstreams__<source>__Password |
Optional Basic authentication instead of a token. |
PackageUpstreams__<source>__Id |
Optional stable source ID: 1–64 ASCII letters, digits, or hyphens. Defaults to the source key. |
Source IDs must be unique within the deployment. Use HTTPS in production. Authenticated upstreams require HTTPS except for loopback development endpoints.
These are standard application configuration keys. The JSON equivalent is PackageUpstreams.npm.Url, for example. A Compose .env file is used for interpolation; adding an arbitrary application key there does not automatically add it to a service’s environment.
Docker Compose setup
Section titled “Docker Compose setup”In the deployment directory containing the reference docker-compose.yml, create .env.upstreams. Replace these URLs and omit any sources you do not want to override:
PackageUpstreams__npm__Url=https://packages.example.com/artifactory/api/npm/npm-public/PackageUpstreams__nuget__Url=https://packages.example.com/repository/nuget-public/v3/index.jsonPackageUpstreams__cargo__Url=sparse+https://packages.example.com/cargo/index/For a mirror requiring Bearer authentication, add a token to the protected file:
PackageUpstreams__npm__Token=<read-only-mirror-token>For Basic authentication, use these two settings instead of Token:
PackageUpstreams__npm__Username=<mirror-service-account>PackageUpstreams__npm__Password=<mirror-password>Use nuget or cargo in those keys to authenticate the other sources. Supply only the chosen method for each source; the angle-bracket values above are placeholders. Keep credentials out of URLs, source control, shell history, and logs. Prefer your organization’s secret-management system for production.
Protect the file:
chmod 600 .env.upstreamsCreate docker-compose.upstreams.yml beside the reference Compose file:
services: portal: env_file: - ./.env.upstreams worker: env_file: - ./.env.upstreams proxy: env_file: - ./.env.upstreams environment: ProxySettings__UseRedirectMode: "false"The shared file keeps upstream definitions consistent across all three services; enrichment still uses public registries. The proxy setting enables forwarding mode, which is required for authenticated upstreams. A redirect cannot transfer credentials held by ShieldedStack to the caller. Anonymous upstreams can use either forwarding or redirect mode. Forwarding alone does not enable persistent caching.
Validate and start from that deployment directory, retaining the normal trial .env for license, database, and identity settings:
docker compose -f docker-compose.yml -f docker-compose.upstreams.yml config --quietdocker compose -f docker-compose.yml -f docker-compose.upstreams.yml up -dUse both -f arguments for subsequent Compose operations. Paths in the override are resolved relative to the first Compose file. Service environment entries take precedence over env_file, so remove conflicting settings from any other overrides. Avoid printing unfiltered docker compose config output: it includes resolved secrets.
Kubernetes with Helm
Section titled “Kubernetes with Helm”The Helm chart accepts the shared packageUpstreams map. Configure sources once; the chart supplies identical settings to the Portal, worker, and proxy:
packageUpstreams: npm: url: https://packages.example.com/repository/npm-public/ tokenSecretRef: name: shieldedstack-package-upstreams key: npm-token nuget: url: https://packages.example.com/repository/nuget-public/v3/index.json usernameSecretRef: name: shieldedstack-package-upstreams key: nuget-username passwordSecretRef: name: shieldedstack-package-upstreams key: nuget-password cargo: url: sparse+https://packages.example.com/cargo/index/Use the same ten source keys listed above, and omit sources you do not override. Secrets must already exist in the release namespace. Choose a token reference or both username/password references, not both methods. Values files contain references, never credential values. Any authenticated source automatically selects forwarding mode; a conflicting redirect setting in proxy.extraEnv is rejected.
Do not mix shared packageUpstreams with per-service PackageUpstreams__* entries in extraEnv. Existing extraEnv-only deployments remain supported when the shared map is empty. Move all source settings together when migrating to the shared map.
URL and Secret name/key changes roll all three application deployments through their changed pod templates. Updating only the contents of an existing Secret does not refresh running environments: restart all three deployments after rotating credentials. A discovered-topology change at the same URL also needs a restart. The chart does not read Secret contents during rendering.
Other deployment platforms
Section titled “Other deployment platforms”Inject the same application settings into the Portal, worker, and proxy using your platform’s configuration and secret mechanisms. Set ProxySettings__UseRedirectMode=false on the proxy for authenticated upstreams, and roll all three services when definitions or credentials change.
Discovery, downloads, and network access
Section titled “Discovery, downloads, and network access”- Supply final registry entry-point URLs. Metadata clients do not automatically follow HTTP redirects.
- Successful endpoint discovery is cached per service process until restart. Failed or cancelled discovery can be retried; services do not need registry network access merely to start.
- npm metadata and artifacts must remain on the same scheme, hostname, and port, within the configured registry mount and supported npm artifact layout.
- NuGet registration and package-content resources must remain on the index’s origin, but may use sibling paths. Required cross-origin resources fail closed; unsupported external search/gallery resources are omitted from the rewritten index.
- Cargo’s trusted bootstrap may authorize a separate HTTPS download CDN and path prefix. Registry credentials are kept on the registry origin, not forwarded to the CDN. A package record cannot introduce a new download origin.
- PyPI file links must stay on the configured origin and within the repository mount.
/simple/and/+simple/entry points permit sibling files below their parent repository directory; other entry points permit files within the supplied mount. Cross-origin file storage is not implicitly authorized by a package page. - Pub and Composer archives must stay within the configured registry resources. Their actual archive URLs are read from that repository after policy allows the requested coordinates, not from a public registry or a caller-supplied download URL. Arbitrary archive redirects that lose identifiable package coordinates fail closed.
- Composer 1 provider-only repositories are not supported as configured upstreams. Composer 2 templates must end in
%package%.json; they may be relative or point to another path on the same origin. Publishing, Git/VCS fallback, and arbitrary external archive hosts are not enabled. - Support for a protocol is not certification of every repository-manager version or configuration. Validate actual package-manager installs against your repository before rollout.
- Allow egress for proxy delivery and discovery to the configured registries and any Cargo download CDN, for advisory lookups to
advisory.shieldedstack.com, and for package metadata lookups to their public sources. A registry mirror does not eliminate public enrichment traffic. Matching private-package patterns suppress those public lookups, not package-manager traffic to the configured source.
Package managers continue using their ShieldedStack API keys. The proxy consumes those keys locally and applies its own upstream authentication where authorized. Do not distribute mirror credentials to developers as a substitute for ShieldedStack authentication.
Apply changes and verify
Section titled “Apply changes and verify”Definitions and successful discovery results are held in memory. After changing source URLs or credentials, recreate all three running application services to load the new environment:
docker compose -f docker-compose.yml -f docker-compose.upstreams.yml up -d --force-recreate --no-deps portal worker proxyThis command is for an already-running deployment. A plain docker compose restart does not reload changed container environment values. On Kubernetes or another orchestrator, roll all three workloads after updating their environment or referenced secrets.
- Run an actual package-manager install through the usual ShieldedStack endpoint, using a ShieldedStack API key.
- Confirm package activity appears under the intended workspace and project in the Portal.
- Check the configured mirror’s access logs for metadata and artifact requests. Avoid logging authorization headers. In redirect mode the caller retrieves the artifact; in forwarding mode the proxy does.
- Confirm a package denied by workspace policy cannot be downloaded through ShieldedStack.
Troubleshooting
Section titled “Troubleshooting”Startup rejects authenticated upstreams. Check that the proxy receives ProxySettings__UseRedirectMode=false. Setting it only in the Compose interpolation .env, without service wiring, is not enough.
Still using the public registry. Public enrichment traffic is expected unless the package matches a private-package pattern. For proxy delivery, confirm the override file is included, the source key is supported, all three services receive the setting, and the deployed images include configurable-upstream support. Recreate the services after environment changes and inspect mirror access logs for package-manager traffic.
502 while discovering or rewriting the source. Check the entry-point URL, DNS/TLS, egress, credential permissions, and the origin/path restrictions above. An unavailable configured source does not trigger a public fallback.
Some package facts are unknown. Enrichment uses public registries, not the configured mirror. A private-package pattern suppresses public collection without supplying replacement facts. Existing facts remain available, missing facts remain unknown, and normal policy still applies.