custom-root-ca.md

Custom Root CA Certificates

Most tools support two ways to extend the default Root CA certificates list.

If you are using a custom base image, checkout Custom base image docs.

Notes

1. Ensure your custom certs are RFC 5280¹ compliant. Especially Python v3.13.0 will reject non-compliant certs.

Buildtime install

This is the easiest method.

FROM containerbase/base

COPY my-root-ca.crt /usr/local/share/ca-certificates/my-root-ca.crt
RUN update-ca-certificates

Buildtime Java install

Containerbase will create a central certificate store at /opt/containerbase/ssl/cacerts when preparing Java (prepare-tool java). This will be used by all Java versions installed by our install-tool. So you can copy your own store like this:

FROM containerbase/base

COPY my-root-cert-store.jks /opt/containerbase/ssl/cacerts

RUN install-tool java <version>

Runtime install

Most OpenSSL base tools (and maybe BoringSSL) support SSL_CERT_FILE environment for additional custom root ca files. If you're using Bun, then you need to set NODE_EXTRA_CA_CERTS environment variable².

docker run --rm -it \
  -v my-root-ca.crt:/my-root-ca.crt \
  -e SSL_CERT_FILE=/my-root-ca.crt \
  containerbase/base bash

Runtime Java install

For Java you need to mount your own certificate store to /opt/containerbase/ssl/cacerts.

docker run --rm -it \
  -v my-root-ca.crt:/my-root-ca.crt \
  -v my-root-cert-store.jks:/opt/containerbase/ssl/cacerts \
  -e SSL_CERT_FILE=/my-root-ca.crt \
  containerbase/base bash

Footnotes

1. https://datatracker.ietf.org/doc/html/rfc5280 ↩

2. https://github.com/oven-sh/bun/issues/271 ↩