Configure registry: dev

Each package manager gets one setting: use the firewall instead of the public registry. Do this per machine, or push the same files with MDM.

Before you start: sfw.example.com resolves to the firewall (DNS record, or /etc/hosts for testing).

Trust the certificate

Skip this if the firewall uses a certificate from a CA your machines already trust. Otherwise copy ssl/fullchain.pem from the firewall host to the developer machine as sfw-ca.pem.

# macOS system trust (curl, pip with recent versions)
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain sfw-ca.pem

# Linux system trust
sudo cp sfw-ca.pem /usr/local/share/ca-certificates/sfw-ca.crt && sudo update-ca-certificates

npm ships its own CA list and does not read the system store by default, so point it at the file directly:

npm config set cafile /path/to/sfw-ca.pem

npm

npm config set registry https://sfw.example.com/npm/

Writes registry=https://sfw.example.com/npm/ to ~/.npmrc. pnpm and Yarn 1 read the same .npmrc. Yarn 2+ uses npmRegistryServer in .yarnrc.yml instead.

pip

pip config set global.index-url https://sfw.example.com/pypi/simple/
pip config set global.cert /path/to/sfw-ca.pem     # only if the CA isn't trusted system-wide

Poetry

poetry source add --priority=primary socket-fw https://sfw.example.com/pypi/simple/
poetry config certificates.socket-fw.cert /path/to/sfw-ca.pem   # only if the CA isn't publicly trusted

🚧

Poetry ignores the system store and pip.conf

Without the certificates setting, a self-signed certificate makes Poetry report the hostname cannot be resolved by your DNS. The real cause shows with -vvv as CERTIFICATE_VERIFY_FAILED.

Other ecosystems

Add the routes you need under path_routing.routes in socket.yml, then docker compose up -d --force-recreate:

    - path: /maven
      upstream: https://repo1.maven.org/maven2
      registry: maven
    - path: /nuget
      upstream: https://api.nuget.org
      registry: nuget
    - path: /go
      upstream: https://proxy.golang.org
      registry: go

Maven runs on the JVM, which has its own truststore. Without the CA there, Maven fails with a misleading No plugin found for prefix error. On Debian/Ubuntu, update-ca-certificates (from Trust the certificate) already adds the CA to the JVM store, so skip this. Elsewhere:

sudo keytool -importcert -noprompt -alias sfw -file sfw-ca.pem -cacerts -storepass changeit   # JDK 9+

Go still fetches checksums from sum.golang.org directly. On networks with locked-down egress, allow that host or set GOSUMDB / GONOSUMDB.

Verify

npm config get registry
npm cache clean --force
npm install lodash     # succeeds
npm install lodahs     # 403, blocked

# Current Debian/Ubuntu block system-wide pip installs (PEP 668), so use a venv
# On a stock Debian/Ubuntu host, first: sudo apt install python3-venv
python3 -m venv .venv && . .venv/bin/activate
pip install --no-cache-dir requests   # succeeds

• Clean installs succeed through the firewall
• npm install lodahs fails with E403
• docker compose logs socket-firewall | grep SOCKET_DECISION on the firewall host shows the requests (needs SOCKET_IGNORE_LOG_LEVEL=warn, set in Block installs with Firewall)

Troubleshooting

📘

Want zero client config?

See DNS override.