Uh oh!
There was an error while loading. Please reload this page.
Correct documentdb-local option reference against upstream source - #61
Merged
guanzhousongmicrosoft merged 6 commits intoAug 3, 2026
Conversation
Follow-up to documentdb#56, which fixed the PG_PORT -> POSTGRESQL_PORT name. The same class of error was present throughout the page. Validated every row of the option table against documentdb-local/scripts/emulator_entrypoint.sh and packaging/gateway/docker/Dockerfile_documentdb_local. Corrections: - --documentdb-port documented PORT; the entrypoint reads DOCUMENTDB_PORT. Identical bug to the one documentdb#56 fixed, five rows above it. - --password was documented as required with default NA. The real default is Admin100, applied before the required-check, so the check never fires. Documented the actual default and why it must be overridden. - --start-pg and --create-user claimed no env var. Both read START_POSTGRESQL / CREATE_USER, and both are set in the Dockerfile. - --start-pg, --create-user, --allow-external-connections and --enable-telemetry all consume a following value but were documented as bare flags. The documented form swallows the next argument. - --cert-path described .pfx certificates and a CERT_SECRET variable. Neither exists; the gateway is always configured with CertType PemFile. - The mandatory --cert-path/--key-file pairing was never stated. Supplying one without the other exits 1 at startup. - Dropped the Azure Application Insights attribution from --enable-telemetry; it appears nowhere in the product. - Added the five supported options that were missing entirely: --tlsMode, --init-data, --init-data-path, --skip-init-data, --disable-extended-rum. --tlsMode governs whether the tls=true examples on this page work. Beyond the table: - Added a readiness step. docker ps reports Up long before the gateway accepts connections; the gateway poll alone allows 60s. Following the page literally produced MongoServerSelectionError. - Certificates are generated on first start and reused, not regenerated every start. The gateway logs "reusing existing certificate" and the reuse is deliberate so client trust pinning survives restart. Same stale sentence corrected in three getting-started pages. - The certificate copy path no longer exists. Auto-generated TLS material now lives under a resolved state directory; the example pins it with DOCUMENTDB_TLS_STATE_DIR rather than hardcoding a path that depends on which directories happen to be writable. - Noted that data is discarded on container removal unless a volume is mounted, and corrected the --data-path example, which was only a bind mount and never changed the data path. - Sample output showed container name optimistic_blackwell despite --name docdb in the command above it, and leaked a real home directory into the mongosh connection string.
Follow-up corrections after validating the page against the upstream entrypoint, Dockerfile, and gateway source: - Certificate section no longer starts a second container. The name and published port collided with the container started under Running, so the page could not be followed top to bottom. It now documents the path the gateway actually resolves to in this image (/home/documentdb/.local/state/documentdb-gateway/tls) and keeps the log-grep as the authoritative check. - Data persistence: the image declares VOLUME ["/data"], so data is orphaned in an anonymous volume, not discarded. - Readiness wait is now a bounded command. "docker logs -f" never returns, because the entrypoint streams logs for the container's life. - --log-level, --enable-telemetry, and --disable-extended-rum are marked as known issues: all three are validated at startup and then have no effect. - Valueless flags (--skip-init-data, --disable-extended-rum) warn that passing a value hangs the argument parser. - --username documents the reserved-name and blocked-prefix constraints. - --owner documents that any non-default value aborts startup. - --allow-external-connections documents the pg_hba rule it adds, the need to publish 9712, and that it is ignored with --start-pg false. - --data-path clarifies that the mount is a docker option and the flag a container argument; adds a complete example. - Certificate stability is scoped to restarts of the same container, and the 365-day validity is stated. Getting-started pages: align the credential and TLS wording with the corrected option table (credentials default rather than being required, default tlsMode accepts plain connections) and carry the readiness step. configuration.md notes the TLS state dir fallback.
…ance - The readiness wait used `timeout`, which is GNU coreutils and not present on macOS. Replaced with a plain `until` loop plus explicit guidance on what a hang means. - The persistence example pinned DOCUMENTDB_TLS_STATE_DIR at a separate named volume. Docker creates such a mount point root-owned and the gateway runs as the unprivileged `documentdb` user, so it could not write the key there. Pinned inside the data volume instead, which the entrypoint chowns on every start, and stated the chmod trade-off. - --owner wording now describes the initialized cluster rather than the image.
…ects No other page in this repo uses in-page anchor links, so the reference to the Running section is now plain text. --start-pg and --create-user had tautological descriptions. Both have real consequences: false means supplying your own PostgreSQL, and false means no admin user is created, so --username / --password do nothing and nothing can authenticate.
--username / --password are still validated and still used by data initialization when --create-user is false; only authentication is impossible. Say that rather than "have no effect".
Third docker run on the page reusing --name docdb and -p 10260:10260; say to remove the earlier container first so the page still reads top to bottom.
guanzhousongmicrosoft
approved these changes
Aug 3, 2026
guanzhousongmicrosoft pushed a commit
that referenced
this pull request
Aug 3, 2026
Two loose ends from #62, both created by pull requests that merged independently of it and could not have known about each other. The contributing instructions in readme.md list the folders that hold documentation articles, and #35 wrote that list while #62 was still open, so it names four folders where there are now five. A contributor following it would not know the kubernetes-operator section exists or that it follows the same rules. The documentdb-local page had no route onward. Someone who has just run the container and wants replication, failover, or rolling upgrades has no reason to guess that the answer is a different section of the site; it is the most likely place in these docs for that question to occur, so it now points at the operator section and at the pre-built packages. This was deliberately held back while #61 was rewriting that page, and lands now that it has merged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Replaces #60, rebased onto current
main(which has since picked up #57, #58, #59 and #35, three of which touch files edited here) and with that PR's review folded in.Follow-up to #56. That PR fixed
PG_PORT->POSTGRESQL_PORT; this validates the rest of the page the same way, againstdocumentdb-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-portwas documented as overridingPORT. The entrypoint readsDOCUMENTDB_PORT. Upstream's owntest_emulator_entrypoint.pyasserts bothPG_PORTandPORTmust be absent from the help output — #56 covered one of the two.Option table
--documentdb-portPORTDOCUMENTDB_PORT--passwordNAAdmin100, set before the required-check so that check never fires--start-pg,--create-userEnv: NASTART_POSTGRESQL/CREATE_USER, both set in the Dockerfile--start-pg,--create-user,--allow-external-connections,--enable-telemetry--cert-path.pfx+CERT_SECRETCertType: PemFile.CERT_SECRETexists nowhere in the product--cert-path/--key-file--enable-telemetry--usernameSTRINGBlockedRolePrefixes(documentdb,citus,pg,internal_role) are rejected before startup--ownerpsql -Urole for admin-user creation;initdbruns with no-Uas thedocumentdbOS user, so that is the only superuser and any other value exits 1 after PostgreSQL has already initialized--allow-external-connectionshost all all 0.0.0.0/0 scram-sha-256, needs-p 9712:9712to be reachable, and is ignored under--start-pg false--start-pg,--create-userfalsemeans bringing your own PostgreSQL / no admin user at all, so nothing can authenticate and data initialization failsThe 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-dataand--disable-extended-rumtake 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.--tlsModeis the notable one: it decides whether plain connections are rejected (requireTLS) or accepted alongside TLS (allowTLS, the default — anddisabled, which despite the name behaves identically).Three options that are documented but inert
--log-level,--enable-telemetry, and--disable-extended-rumare all parsed and strictly validated by the entrypoint and then have no effect:LOG_LEVELnever reaches the gateway, which reads onlyDOCUMENTDB_LOG_LEVEL(atracingEnvFilterstring, in whichquietis not a level).ENABLE_TELEMETRYis exported and never read again;SetupConfiguration.jsonshipsMetrics/TracingEnabled: falseand the entrypoint never rewrites them.--disable-extended-rumis implemented by omitting-rfromstart_oss_server.sh, but that script defaultsuseDocumentdbExtendedRum="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
docker psreportsUplong before the gateway accepts connections; the gateway readiness poll alone allows 60s. Following the page literally gaveMongoServerSelectionError. The wait is a boundeduntil ... grep -qloop rather thandocker logs -f, which never returns — the entrypointtail -Fs four log files into stdout for the container's whole life. It deliberately avoidstimeout, which is GNU coreutils and absent on macOS.docker rm+docker runmints 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./var/lib/documentdb-gateway/tlsis created by the gateway DEB's packaging, not by this image, and the container runs as non-rootdocumentdb— so resolution falls through to$HOME/.local/state/documentdb-gateway/tls. The page now names that path and keepsdocker logs | grep "TLS auto-gen"as the authoritative check. The persistence option pinsDOCUMENTDB_TLS_STATE_DIRinside the data volume, which the entrypoint chowns on every start; a volume of its own is created root-owned and the unprivileged gateway cannot write its key there. Thechmod -R 750trade-off that comes with/datais stated rather than hidden.VOLUME ["/data"], so without an explicit mount the data is stranded in an anonymous volume rather than discarded. Fixed the--data-pathexample, which was only a bind mount and never actually changed the data path, and added one completedocker runshowing that-vgoes before the image name and--data-pathafter it.optimistic_blackwelldespite--name docdbin 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--passwordrow. "DocumentDB Local requires TLS" became "accepts TLS connections … and requires authentication", since the defaultallowTLSdoes not reject plain clients. All three pages carry the same readiness wait.postgres-api/configuration.mdnotes theDOCUMENTDB_TLS_STATE_DIRfallback 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.