Name the NEPTUNE_NOTEBOOK/HTTPS conflict instead of blaming missing certs

[kmcginnes]

Description

When NEPTUNE_NOTEBOOK and PROXY_SERVER_HTTPS_CONNECTION are both true, the server now refuses to start and says why. Before, this pair failed with "certificate files are missing", which sent people looking for certificates the notebook preset never generates.

How the pieces fit:

• NEPTUNE_NOTEBOOK is in EnvironmentValuesSchema now. It parses with an exact match on "true", the same test process-environment.sh and the entrypoint use, and it never fails the parse. TRUE or 1 mean "not the preset" in all three places.

• A superRefine on the schema rejects the pair at PROXY_SERVER_HTTPS_CONNECTION, with a message that names both variables and both ways out. The parse runs before resolveServerConfig looks for certificates, so the operator sees the conflict first. resolveServerConfig goes back to checking only files on disk.

• process-environment.sh keeps an HTTPS value under the preset only when it reads as true in any case, and otherwise applies the preset's false as before. That way a config.json null, 0 or "yes" still serves HTTP. On main the preset overwrote the value it had just read from config.json, so the preset could discard an explicit HTTPS request without an error. A config.json with both true used to serve HTTP. Now it refuses.

• docker-entrypoint.sh skips setup-ssl.sh under the preset, because an HTTP-only server never uses the certificates. Without that, a notebook container with no HOST would exit in setup-ssl.sh before the server could name the conflict.

• The entrypoint starts node with the NEPTUNE_NOTEBOOK value from .env. The container's own value can differ from .env, since config.json replaces it, and dotenv never overrides a variable that's already set. Passing the .env value means the server checks for the conflict exactly when the shell applied the preset.

• Restarts. process-environment.sh appends to .env on every start, and a container keeps that file across docker restart and --restart always. The entrypoint read every matching line for NEPTUNE_NOTEBOOK, so on the second start it came through as true\ntrue, the preset check failed, and the certificate error came back. That read now takes the last line, which is what dotenv does.

  PROXY_SERVER_HTTPS_CONNECTION keeps its original first-match read on purpose. A restarted TLS container's .env also gets a repeated true, and the first-match read doesn't satisfy the exact "true" check, so setup-ssl.sh is skipped. The container keeps serving TLS on the certificate from its first start instead of generating a new one and breaking trust for anyone who accepted the original root CA.

Breaking changes

• Setting NEPTUNE_NOTEBOOK=true and PROXY_SERVER_HTTPS_CONNECTION=true together now refuses to start. That includes a config.json with both true, which used to serve HTTP.
• The same applies to the notebook preset with -e PROXY_SERVER_HTTPS_CONNECTION=true and certificates mounted into the container. On main I expect that setup served TLS, since the shell skipped generation and the server found the mounted files. I doubt anyone runs it, but it's a change. The error names both ways out.
• The conflict reaches the logs as console.error("Failed to parse environment values") instead of a pino FATAL line, and under the preset the log style is cloudwatch. An alarm that matches FATAL won't fire on it. The exit code is still 1. The certificate skip message also changed from "SSL disabled. Skipping..." to "Neptune Notebook preset enabled. Skipping...".

Validation

config-pipeline.test.ts has a scenario table. Each row runs the real docker-entrypoint.sh and process-environment.sh, with only setup-ssl.sh and the node start stubbed, then applies dotenv precedence, the Zod schema and resolveServerConfig. Rows cover both images (NEPTUNE_NOTEBOOK set to "" or true), -e values, config.json, a missing HOST, and a second start in the same container. Each asserts what lands in .env, whether certificates get generated, and what the server does at startup. Parse-failure rows check which key failed.

I ran the table against main's scripts and server code. The only rows that differ are the ones where both values end up true, which now refuse instead of failing later on missing certificates. The TLS restart row matches main: certificates aren't regenerated on the second start, and the container keeps serving TLS on the certificate from the first. Rows for known quirks pin what happens today. For example, config.json with HTTPS true plus -e PROXY_SERVER_HTTPS_CONNECTION=false generates certificates and then serves HTTP. That precedence split is tracked in #1673.

I also ran both images in Docker:

• Notebook image with -e PROXY_SERVER_HTTPS_CONNECTION=true exits 1 with the conflict message. docker start on the same container gives the same message.
• Standard image with HOST=localhost serves TLS, and still serves TLS on the same root CA fingerprint after docker restart.

docs/agents/testing.md now describes the entrypoint test harness, and docs/adr/20260925-refuse-neptune-notebook-https-conflict.md records why the pair is refused instead of letting one side win.

pnpm checks and pnpm test pass: 224 files, 2819 tests.

Related Issues

• Related to TypeScript configuration pipeline replacing process-environment.sh #1673

Check List

• I confirm that my contribution is made under the terms of the Apache 2.0 license.
• I have verified pnpm checks passes with no errors.
• I have verified pnpm test passes with no failures.
• I have covered new added functionality with unit tests if necessary.
• I have updated documentation if necessary.