fix: add certs folder

README.md

@@ -74,15 +74,9 @@ NODE_VERSION=24.21.0 OPENCODE_VERSION=2.0.3 ./build.sh --no-cache
 
 ## Custom CA certificates
 
-Custom CA certificates must be placed in the repository `certs/` directory before building the image.
+Custom CA certificates must be placed in the repository `certs/` directory before building the image. See [`certs/README.md`](certs/README.md) for accepted formats and rules.
 
-Example:
+This directory is kept in git through a placeholder file, so a fresh clone builds without creating it first.
-
-```text
-certs/
-├── company-root.crt
-└── company-intermediate.crt
-```
 
 The Dockerfile copies this directory to:
 
@@ -104,7 +98,7 @@ NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
 
 This allows both system tools and Node.js applications to trust the additional certificates.
 
-**Important:** CA certificates need to be present when the image is built. The runtime container does not install certificates from the host.
+**Important:** CA certificates need to be present when the image is built. The runtime container does not install certificates from the host. After adding or removing a certificate, rebuild with `./build.sh --no-cache --update`.
 
 ## Run the container
 

build.sh

@@ -18,7 +18,6 @@ BUILD_OPTS=()
 DRY_RUN=0
 REMOVE=0
 PRUNE=0
-# EXTRA_APT_PACKAGES="${EXTRA_APT_PACKAGES:-}"
 EXTRA_APT_PACKAGES=()
 
 while (($#)); do

certs/README.md

@@ -0,0 +1,72 @@
+# 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.