Autograph
dev

Custom CA certificates

When a corporate proxy re-signs HTTPS traffic, the tools making TLS connections must trust its certificate authority (CA). Squid only tunnels HTTPS and needs no corporate CA.

Configure

Does your proxy inspect TLS?

If it does, builds fail with CERTIFICATE_VERIFY_FAILED or unable to get local issuer certificate. To check beforehand, show who signs a public site's certificate through your proxy:

host terminal (proxy without authentication)
openssl s_client -proxy proxy.corp.example:8080 -connect registry.npmjs.org:443 -servername registry.npmjs.org </dev/null 2>/dev/null | openssl x509 -noout -issuer

A company or security-vendor issuer means inspection: configure the CA below.

Set this variable in env/.env.augr. Leave it empty if TLS is not inspected.

VariablePurposeExample
AUGR_NET_CA_CERT_DIRHost directory holding corporate CA certificates as .crt or .pem files/usr/local/share/ca-certificates/autograph

Gather all required corporate CA certificates in a dedicated host directory:

  • Obtain the trusted certificates from your IT team. For example, use /usr/local/share/ca-certificates/autograph/ on Debian/Ubuntu-based hosts. The directory setting alone does not update the host's own trust store.
  • Each image owner copies the certificates into its own gitignored build context before building, then adds them to the image's system trust store.
  • West (engine), the agent (its package), and the seed's node-dev and rust-dev images (project) implement this copy. Node images also set NODE_EXTRA_CA_CERTS.
  • No CA mount or TLS interception is needed in squid. Do not add CA steps to other images without a certificate failure that shows the need.

Apply

Set the directory before installation so West can build with it. Certificates are baked into images, not loaded by a proxy restart. For an existing installation, rebuild the affected images; validate the dev agent before rolling its shared image to metalab:

terminal
task augr:build
task augr:engine:west:build
task augr:pkg:agent:rebuild
# Validate the dev agent before continuing
task augr:pkg:metalab:reup
task app:rebuild

Run task augr:up before app builds: the seed app needs the stack's networks. Package tasks still require Compose v2; see the v1 limitation before using these commands on a v1 workstation.

Verify

Each build reports the certificates it bakes into its image, for example:

build output
[OK] West: 2 CA certificate(s) from /usr/local/share/ca-certificates/autograph
[OK] Agent: 2 CA certificate(s) from /usr/local/share/ca-certificates/autograph
[OK] App: 2 CA certificate(s) from /usr/local/share/ca-certificates/autograph

The count must match the files in your directory, and the builds must finish without certificate errors. Never work around such errors by disabling certificate verification.

Learn more

Which images trust the corporate CA, and why the proxy does not need it, is described in Security.