Correct documentdb-local option reference against upstream source

[GuanzhouSong]

Follow-up to #56. That PR fixed PG_PORT -> POSTGRESQL_PORT; this validates the rest of the page the same way, against documentdb-local/scripts/emulator_entrypoint.sh, packaging/gateway/docker/Dockerfile_documentdb_local, scripts/start_oss_server.sh, and the gateway's TLS source.

The same bug, five rows up

--documentdb-port was documented as overriding PORT. The entrypoint reads DOCUMENTDB_PORT. Upstream's own test_emulator_entrypoint.py asserts both PG_PORT and PORT must be absent from the help output — #56 covered one of the two.

Option table

Row	Was	Actually
--documentdb-port	PORT	DOCUMENTDB_PORT
--password	required, default NA	default Admin100, set before the required-check so that check never fires
--start-pg, --create-user	Env: NA	START_POSTGRESQL / CREATE_USER, both set in the Dockerfile
--start-pg, --create-user, --allow-external-connections, --enable-telemetry	bare flags	all consume a following value
--cert-path	.pfx + CERT_SECRET	PEM only; the gateway is always configured CertType: PemFile. CERT_SECRET exists nowhere in the product
--cert-path / --key-file	described standalone	mandatory pairing; supplying one without the other exits 1
--enable-telemetry	"Azure Application Insights"	no such integration exists in the product
--username	STRING	reserved role names and the BlockedRolePrefixes (documentdb, citus, pg, internal_role) are rejected before startup
--owner	"Specify the owner for DocumentDB"	the psql -U role for admin-user creation; the image has only documentdb, so any other value exits 1 after PostgreSQL has already initialized
--allow-external-connections	"opens PostgreSQL"	also adds host all all 0.0.0.0/0 scram-sha-256, needs -p 9712:9712 to be reachable, and is ignored under --start-pg false

The bare-flag ones matter more than they look: the argument parser has no *) catch-all, so a value-consuming flag written in its documented bare form swallows the next argument and the parse loop stops making progress. The inverse is worse — --skip-init-data and --disable-extended-rum take no value, and passing one (--disable-extended-rum false) leaves the parser re-testing the same argv forever: no logs, no ready banner, no exit. Both rows now say so.

Five supported options were missing entirely:--tlsMode, --init-data, --init-data-path, --skip-init-data, --disable-extended-rum. --tlsMode is the notable one: it decides whether plain connections are rejected (requireTLS) or accepted alongside TLS (allowTLS, the default — and disabled, which despite the name behaves identically).

Three options that are documented but inert

--log-level, --enable-telemetry, and --disable-extended-rum are all parsed and strictly validated by the entrypoint and then have no effect:

• LOG_LEVEL never reaches the gateway, which reads only DOCUMENTDB_LOG_LEVEL (a tracingEnvFilter string, in which quiet is not a level).
• ENABLE_TELEMETRY is exported and never read again; SetupConfiguration.json ships Metrics/TracingEnabled: false and the entrypoint never rewrites them.
• --disable-extended-rum is implemented by omitting-r from start_oss_server.sh, but that script defaults useDocumentdbExtendedRum="true", so extended RUM stays on.

These are product-side, so the page marks them Known issue rather than papering over them. Filing separately against documentdb/documentdb.

Beyond the table

• Readiness step added.docker ps reports Up long before the gateway accepts connections; the gateway readiness poll alone allows 60s. Following the page literally gave MongoServerSelectionError. The wait is a bounded until ... grep -q rather than docker logs -f, which never returns — the entrypoint tail -Fs four log files into stdout for the container's whole life.
• Certificates are reused, not regenerated — but only across restarts of the same container; docker rm + docker run mints a new one unless the state dir is persisted. Validity is 365 days with no renewal and no expiry check on the reuse path, so both facts are now stated. The same stale "new certificate on each start" sentence was in three getting-started pages; corrected there too.
• Certificate copy path no longer exists. Auto-generated TLS material moved to a resolved state directory. The documented default /var/lib/documentdb-gateway/tls is created by the gateway DEB's packaging, not by this image, and the container runs as non-root documentdb — so resolution falls through to $HOME/.local/state/documentdb-gateway/tls. The page now names that path, keeps docker logs | grep "TLS auto-gen" as the authoritative check, and no longer starts a second container to pin DOCUMENTDB_TLS_STATE_DIR (that example collided with the running container's name and published port). Where it does mention pinning, it warns to stay outside --data-path, which the entrypoint chmod -R 750s on every start.
• Data persistence. The image declares VOLUME ["/data"], so without an explicit mount the data is stranded in an anonymous volume rather than discarded. Fixed the --data-path example, which was only a bind mount and never actually changed the data path, and added one complete docker run showing that -v goes before the image name and --data-path after it.
• Sample output. Showed optimistic_blackwell despite --name docdb in the command above it, and leaked a real home directory (/Users/<name>/) into the mongosh connection string.

Getting-started pages

Aligned with the corrected option table: the credential notes said the username and password "must be set … for authentication to work", which is false — omitting them silently selects the public default_user / Admin100, so they now carry the same warning as the --password row. "DocumentDB Local requires TLS" became "accepts TLS connections … and requires authentication", since the default allowTLS does not reject plain clients. All three pages carry the same readiness wait. postgres-api/configuration.md notes the DOCUMENTDB_TLS_STATE_DIR fallback so it no longer contradicts this page.

---

Written with assistance from Claude Code; every claim above was verified against the upstream source tree by a human before submitting.

[GuanzhouSong]

Upstream companion: documentdb/documentdb#711.

Several errors corrected here turned out to be faithful transcriptions of emulator_entrypoint.sh --help — the .pfx/CERT_SECRET rows, the Azure Application Insights attribution, --password as required, and the missing env vars on --start-pg/--create-user. That PR fixes the help text at the source and adds regression tests, so the two do not drift apart again.

The two product-side findings noted above (LOG_LEVEL and ENABLE_TELEMETRY parsed but never plumbed to the gateway) are described in that PR's description as deliberately out of scope for it — they need a behavior change, not a text fix.

[GuanzhouSong]

Closing in favour of a clean replacement.

This branch had drifted: main has since picked up #57, #58, #59 and #35, three of which touch files this PR edits. The successor is rebased onto current main, and it folds in everything from the review on this PR — the certificate section no longer starts a conflicting second container, the docker cp path is the one the gateway actually resolves to in this image, the /data volume wording is corrected, the readiness wait terminates, and --log-level / --enable-telemetry / --disable-extended-rum are marked as known issues rather than documented as working.

Superseded by the PR linked below.

[GuanzhouSong]

Superseded by #61.