# Custom CA certificates

Place any **additional CA certificates** needed to reach internal HTTPS services
in this directory, as PEM files with a `.crt` or `.pem` extension:

```text
certs/
├── .gitignore
├── 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. The `.gitignore` in this directory blocks those extensions, but it
  is a safety net, not a guarantee.
* Files must be PEM encoded. Convert DER with:

  ```bash
  openssl x509 -inform der -in cert.der -out cert.crt
  ```

## Troubleshooting

If a certificate seems ignored, check that it parses and that the build picked
it up:

```bash
openssl x509 -in company-root.crt -noout -subject -issuer -dates
```

A build that prints warnings from `update-ca-certificates` usually means a file
in this directory is not a valid PEM certificate. The permissive `.crt`/`.pem`
extensions mean a stray text file or archive will be picked up and rejected.