# 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.