Ian
79 lines
2.0 KiB
Markdown
79 lines
2.0 KiB
Markdown
# Custom CA certificates
|
|
|
|
Place any **additional CA certificates** needed to reach internal HTTPS services
|
|
in this directory, as PEM files with a `.crt` extension:
|
|
|
|
```text
|
|
certs/
|
|
├── README.md
|
|
├── company-root.crt
|
|
└── company-intermediate.crt
|
|
```
|
|
|
|
This file also guarantees the directory exists in a fresh clone. The build
|
|
copies `certs/` into the image and runs `update-ca-certificates`, so it fails if
|
|
the directory is missing.
|
|
|
|
## How they are installed
|
|
|
|
`Dockerfile` copies this directory to:
|
|
|
|
```text
|
|
/usr/local/share/ca-certificates
|
|
```
|
|
|
|
and runs:
|
|
|
|
```bash
|
|
update-ca-certificates
|
|
```
|
|
|
|
The resulting system CA bundle is also exposed to Node.js through:
|
|
|
|
```text
|
|
NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
|
|
```
|
|
|
|
so both system tools and Node.js applications trust the added certificates.
|
|
|
|
## Rules
|
|
|
|
* Certificates are baked in at **build time**. The runtime container does not
|
|
install certificates from the host, so there is no need to mount this
|
|
directory into the container.
|
|
* Rebuild after any change:
|
|
|
|
```bash
|
|
./build.sh --no-cache --update
|
|
```
|
|
|
|
* Only **public** CA certificates belong here. Never commit private material
|
|
(`*.key`, `*.p12`, `*.pfx`) — everything matched here is copied into the image
|
|
verbatim.
|
|
* Files must be PEM encoded and use the `.crt` extension. Any other extension
|
|
(`.pem`, `.cer`, …) is **silently ignored** by `update-ca-certificates`, so
|
|
rename it to `.crt`. Convert DER with:
|
|
|
|
```bash
|
|
openssl x509 -inform der -in cert.der -out cert.crt
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
If a certificate seems ignored, the most likely cause is the extension: only
|
|
files ending in `.crt` are installed. A `.pem` file produces no error and no
|
|
warning, it is simply skipped. Rename it:
|
|
|
|
```bash
|
|
mv company-root.pem company-root.crt
|
|
```
|
|
|
|
Otherwise check that the file parses as a certificate:
|
|
|
|
```bash
|
|
openssl x509 -in company-root.crt -noout -subject -issuer -dates
|
|
```
|
|
|
|
A build that prints warnings from `update-ca-certificates` means a `.crt` file
|
|
is present but is not valid PEM certificate data.
|