From 839e2a925d4535cc41e5799ab80814a8b893b2a1 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Mon, 3 Aug 2026 10:52:42 -0400 Subject: [PATCH 1/6] Correct documentdb-local option reference against upstream source Follow-up to #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 #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. --- documentdb-local/index.md | 65 ++++++++++++++++++----- getting-started/mongo-shell-quickstart.md | 2 +- getting-started/nodejs-setup.md | 2 +- getting-started/python-setup.md | 2 +- 4 files changed, 54 insertions(+), 17 deletions(-) diff --git a/documentdb-local/index.md b/documentdb-local/index.md index 92a9fc9..a5472ab 100644 --- a/documentdb-local/index.md +++ b/documentdb-local/index.md @@ -33,9 +33,27 @@ docker ps ```output CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -5aff734a3591 ghcr.io/documentdb/documentdb/documentdb-local:latest "/bin/bash -c '/home…" 5 seconds ago Up 4 seconds 0.0.0.0:10260->10260/tcp, :::10260->10260/tcp optimistic_blackwell +5aff734a3591 ghcr.io/documentdb/documentdb/documentdb-local:latest "/bin/bash -c '/home…" 5 seconds ago Up 4 seconds 0.0.0.0:10260->10260/tcp, :::10260->10260/tcp docdb ``` +> This container writes its data to `/data` inside the container. Nothing is mounted there in the command above, so the database is discarded when the container is removed. See `--data-path` in the table below to persist it. + +### Wait for the container to be ready + +`docker ps` reports the container as `Up` well before DocumentDB can accept connections - PostgreSQL has to initialize, the extensions have to be set up, and the admin user has to be created first. Connecting too early fails with `MongoServerSelectionError` or `ECONNREFUSED`. + +Wait for the ready banner in the logs before connecting: + +```bash +docker logs -f docdb +``` + +```output +=== DocumentDB is ready === +``` + +First start typically takes a few tens of seconds. + > The DocumentDB gateway endpoint is available on port `10260` by default. To access this with `mongosh`, run: ```bash @@ -62,18 +80,23 @@ The following table summarizes the available Docker commands for configuring the |---|---|---|---|---|---| | Print the settings to stdout from the container | `--help`, `-h` | N/A | N/A | N/A | Display information on available configuration | | Specify the username for DocumentDB. | `--username [value]` | Overrides `USERNAME` environment variable | STRING | `default_user` | Username for DocumentDB. | -| Specify the password for DocumentDB. | `--password [value]` | Overrides `PASSWORD` environment variable | STRING | NA | Password for DocumentDB. This is required. | -| The port of the DocumentDB endpoint. | `--documentdb-port [value]` | Overrides `PORT` environment variable | INT | `10260` | The port needs to published - for example, using `-p 10260:10260`. | -| Specify a directory for data. | `--data-path [value]` | Overrides `DATA_PATH` environment variable. | STRING | `/data` | For example, to set `/usr/documentdb/data` as data directory, add this option to `docker run` command: `--mount type=bind,source=./.local/data,target=/usr/documentdb/data` | +| Specify the password for DocumentDB. | `--password [value]` | Overrides `PASSWORD` environment variable | STRING | `Admin100` | Password for DocumentDB. Always set this explicitly. The built-in default is well known, and anyone who can reach the published port can authenticate with it. | +| The port of the DocumentDB endpoint. | `--documentdb-port [value]` | Overrides `DOCUMENTDB_PORT` environment variable | INT | `10260` | The port needs to be published - for example, using `-p 10260:10260`. | +| Specify a directory for data. | `--data-path [value]` | Overrides `DATA_PATH` environment variable. | STRING | `/data` | Data is not persisted unless you mount a volume at this path - for example, `-v documentdb-data:/data`. To use a different directory, set the flag and the mount together: `--data-path /usr/documentdb/data` with `--mount type=bind,source=./.local/data,target=/usr/documentdb/data`. | | Specify the owner. | `--owner [value]` | Overrides `OWNER` environment variable. | STRING | `documentdb` | Specify the owner for DocumentDB. | -| Specify whether to start the PostgreSQL server. | `--start-pg` | NA | `true`, `false` | `true` | Specify whether to start the PostgreSQL server. | -| Specify whether to create a user. | `--create-user` | NA | `true`, `false` | `true` | Specify whether to create a user. | +| Specify whether to start the PostgreSQL server. | `--start-pg [value]` | Overrides `START_POSTGRESQL` environment variable | `true`, `false` | `true` | Specify whether to start the PostgreSQL server. | +| Specify whether to create a user. | `--create-user [value]` | Overrides `CREATE_USER` environment variable | `true`, `false` | `true` | Specify whether to create a user. | | Specify the port for the PostgreSQL server. | `--pg-port [value]` | Overrides `POSTGRESQL_PORT` environment variable | INT | `9712` | Specify the port for the PostgreSQL server. | -| Specify whether to allow external connections to PostgreSQL. | `--allow-external-connections` | Overrides `ALLOW_EXTERNAL_CONNECTIONS` environment variable | `true`, `false` | `false` | Specify whether to allow external connections to PostgreSQL. | -| Specify the path to a certificate for securing traffic. | `--cert-path [value]` | Overrides `CERT_PATH` environment variable. | STRING | NA | You need to mount this file into the container. For example, to set `/mycert.pfx`, add this option to `docker run` command: `--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`. Can set `CERT_SECRET` to the password for the certificate. | -| Override default key with key in key file. | `--key-file [value]` | Overrides `KEY_FILE` environment variable. | STRING | NA | You need to mount this file into the container. For example, to set `/mykey.key`, add this option to `docker run` command: `--mount type=bind,source=./mykey.key,target=/mykey.key` | -| Enable telemetry data. | `--enable-telemetry` | Overrides `ENABLE_TELEMETRY` environment variable | `true`, `false` | `false` | Enable telemetry data sent to the usage collector (Azure Application Insights). | -| Specify log verbosity. | `--log-level [value]` | Overrides `LOG_LEVEL` environment variable. | `quiet`, `error`, `warn`, `info`, `debug`, `trace` | `info` | The verbosity of logs that will be emitted. | +| Specify whether to allow external connections to PostgreSQL. | `--allow-external-connections [value]` | Overrides `ALLOW_EXTERNAL_CONNECTIONS` environment variable | `true`, `false` | `false` | Opens the container's internal PostgreSQL server to all interfaces. This does not affect the gateway, which always listens on all interfaces on the DocumentDB port. | +| Specify the path to a certificate for securing traffic. | `--cert-path [value]` | Overrides `CERT_PATH` environment variable. | STRING | NA | PEM-format certificate. Must be set together with `--key-file` - setting only one of the two fails at startup. You need to mount this file into the container. For example, to set `/mycert.pem`, add this option to `docker run` command: `--mount type=bind,source=./mycert.pem,target=/mycert.pem`. | +| Override default key with key in key file. | `--key-file [value]` | Overrides `KEY_FILE` environment variable. | STRING | NA | PEM-format private key. Must be set together with `--cert-path` - setting only one of the two fails at startup. You need to mount this file into the container. For example, to set `/mykey.key`, add this option to `docker run` command: `--mount type=bind,source=./mykey.key,target=/mykey.key` | +| Set the TLS mode for client connections. | `--tlsMode [value]` | Overrides `TLS_MODE` environment variable | `disabled`, `allowTLS`, `requireTLS` | `allowTLS` | With `allowTLS` the gateway accepts both plain and TLS connections; `disabled` behaves the same way. `requireTLS` rejects plain connections, so every client must connect with `tls=true`. | +| Enable initialization with built-in sample data. | `--init-data [value]` | Overrides `INIT_DATA` environment variable | `true`, `false` | `false` | Seeded once per data volume, on a fresh volume. Re-create the volume to seed again. | +| Specify a directory of scripts for database initialization. | `--init-data-path [value]` | Overrides `INIT_DATA_PATH` environment variable | STRING | `/init_doc_db.d` | JavaScript files are executed in alphabetical order using `mongosh`, once per fresh data volume. Scripts should be idempotent - a failed run is not retried on restart. | +| Skip initialization with built-in sample data. | `--skip-init-data` | Overrides `SKIP_INIT_DATA` environment variable | N/A | N/A | Legacy alias for `--init-data false`. Does not affect `--init-data-path`. | +| Disable the use of extended RUM for indexes. | `--disable-extended-rum` | Overrides `DISABLE_EXTENDED_RUM` environment variable | N/A | `false` | Extended RUM is enabled by default. | +| Enable telemetry data. | `--enable-telemetry [value]` | Overrides `ENABLE_TELEMETRY` environment variable | `true`, `false` | `false` | Enable telemetry data sent to the usage collector. | +| Specify log verbosity. | `--log-level [value]` | Overrides `LOG_LEVEL` environment variable. | `quiet`, `error`, `warn`, `info`, `debug`, `trace` | `info` | The verbosity of logs that will be emitted. To set the gateway's own log level, use the `DOCUMENTDB_LOG_LEVEL` environment variable. | ## Feature support @@ -83,15 +106,29 @@ Please refer to the [documentdb](https://documentdb.io/docs/) documentation for ## Installing certificates -By default, DocumentDB Local generates new self-signed certificates each time the container starts. To prevent certificate errors, install them on your local machine. The example below shows how to use this setup with `mongosh`. +If you do not supply your own certificate with `--cert-path` and `--key-file`, DocumentDB Local generates a self-signed certificate on first start and reuses it on subsequent starts, so the certificate stays stable across restarts. To prevent certificate errors, install it on your local machine. The example below shows how to use this setup with `mongosh`. ### Get certificate +The gateway chooses where to store auto-generated TLS material based on which directories are writable, so pin the location with `DOCUMENTDB_TLS_STATE_DIR` when starting the container: + +```bash +docker run -dt -p 10260:10260 --name docdb \ + -e DOCUMENTDB_TLS_STATE_DIR=/data/tls \ + ghcr.io/documentdb/documentdb/documentdb-local:latest --username demo --password test +``` + In a `bash` window, run the following to copy the certificate from the container to the local host: ```bash -docker cp docdb:/home/documentdb/gateway/pg_documentdb_gw/cert.pem ~/documentdb-cert.pem +docker cp docdb:/data/tls/cert.pem ~/documentdb-cert.pem +``` + +If you did not set `DOCUMENTDB_TLS_STATE_DIR`, the gateway logs the path it chose on startup: + +```bash +docker logs docdb | grep "TLS auto-gen" ``` ### Use the certificate with mongosh @@ -102,7 +139,7 @@ mongosh localhost:10260 -u demo -p test --authenticationMechanism SCRAM-SHA-256 ```output Current Mongosh Log ID: 690ce1171181053c6edbf354 -Connecting to: mongodb://@localhost:10260/?directConnection=true&serverSelectionTimeoutMS=2000&authMechanism=SCRAM-SHA-256&tls=true&tlsCAFile=%2FUsers%2Fgeeichbe%2Fdocumentdb-cert.pem&appName=mongosh+2.5.1 +Connecting to: mongodb://@localhost:10260/?directConnection=true&serverSelectionTimeoutMS=2000&authMechanism=SCRAM-SHA-256&tls=true&tlsCAFile=%2Fhome%2Fuser%2Fdocumentdb-cert.pem&appName=mongosh+2.5.1 Using MongoDB: 7.0.0 Using Mongosh: 2.5.1 mongosh 2.5.9 is available for download: https://www.mongodb.com/try/download/shell diff --git a/getting-started/mongo-shell-quickstart.md b/getting-started/mongo-shell-quickstart.md index 69dd1c9..0169c59 100644 --- a/getting-started/mongo-shell-quickstart.md +++ b/getting-started/mongo-shell-quickstart.md @@ -40,7 +40,7 @@ docker ps ## Connecting to DocumentDB -DocumentDB Local terminates TLS on the gateway port. The container generates a new self-signed certificate on each start, so the simplest local connection skips certificate validation with `tlsAllowInvalidCertificates=true`. +DocumentDB Local terminates TLS on the gateway port. The container generates a self-signed certificate on first start and reuses it thereafter, so the simplest local connection skips certificate validation with `tlsAllowInvalidCertificates=true`. ```bash mongosh "mongodb://:@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true" diff --git a/getting-started/nodejs-setup.md b/getting-started/nodejs-setup.md index 385bebe..482e9f4 100644 --- a/getting-started/nodejs-setup.md +++ b/getting-started/nodejs-setup.md @@ -52,7 +52,7 @@ Before connecting from Node.js, make sure you have a running DocumentDB instance ## Connecting to DocumentDB -DocumentDB Local requires TLS and authentication on the gateway port. Connect with the username and password you set when starting the container, and because the container generates a new self-signed certificate on each start, the simplest local setup skips certificate validation with `tlsAllowInvalidCertificates=true` (in production, provide the gateway certificate instead). +DocumentDB Local requires TLS and authentication on the gateway port. Connect with the username and password you set when starting the container, and because the container uses a self-signed certificate, the simplest local setup skips certificate validation with `tlsAllowInvalidCertificates=true` (in production, provide the gateway certificate instead). ```javascript const { MongoClient } = require('mongodb'); diff --git a/getting-started/python-setup.md b/getting-started/python-setup.md index 7ddefcf..05d53ee 100644 --- a/getting-started/python-setup.md +++ b/getting-started/python-setup.md @@ -48,7 +48,7 @@ Learn how to set up and use DocumentDB with Python using the official MongoDB Py ## Connecting to DocumentDB -DocumentDB Local requires TLS and authentication on the gateway port. Connect with the username and password you set when starting the container, and because the container generates a new self-signed certificate on each start, the simplest local setup skips certificate validation with `tlsAllowInvalidCertificates=true` (in production, provide the gateway certificate instead). +DocumentDB Local requires TLS and authentication on the gateway port. Connect with the username and password you set when starting the container, and because the container uses a self-signed certificate, the simplest local setup skips certificate validation with `tlsAllowInvalidCertificates=true` (in production, provide the gateway certificate instead). 1. Basic Connection ```python From 12217f69e38025a92dd39ba81637647ad880a1e6 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Mon, 3 Aug 2026 12:26:03 -0400 Subject: [PATCH 2/6] Address review findings on documentdb-local option reference 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. --- documentdb-local/index.md | 65 +++++++++++++---------- getting-started/mongo-shell-quickstart.md | 12 +++-- getting-started/nodejs-setup.md | 6 ++- getting-started/python-setup.md | 6 ++- postgres-api/configuration.md | 2 +- 5 files changed, 55 insertions(+), 36 deletions(-) diff --git a/documentdb-local/index.md b/documentdb-local/index.md index a5472ab..f631c77 100644 --- a/documentdb-local/index.md +++ b/documentdb-local/index.md @@ -36,23 +36,24 @@ CONTAINER ID IMAGE 5aff734a3591 ghcr.io/documentdb/documentdb/documentdb-local:latest "/bin/bash -c '/home…" 5 seconds ago Up 4 seconds 0.0.0.0:10260->10260/tcp, :::10260->10260/tcp docdb ``` -> This container writes its data to `/data` inside the container. Nothing is mounted there in the command above, so the database is discarded when the container is removed. See `--data-path` in the table below to persist it. +> This container writes its database to `/data`, which the image declares as a Docker volume. The command above mounts nothing there, so each `docker run` gets a fresh anonymous volume: the data does not survive re-creating the container, and the old volume is left behind on the host until you prune it. Mount a named volume - `-v documentdb-data:/data` - to persist it. See `--data-path` in the table below. ### Wait for the container to be ready `docker ps` reports the container as `Up` well before DocumentDB can accept connections - PostgreSQL has to initialize, the extensions have to be set up, and the admin user has to be created first. Connecting too early fails with `MongoServerSelectionError` or `ECONNREFUSED`. -Wait for the ready banner in the logs before connecting: +The entrypoint prints a ready banner once the gateway is accepting connections. Wait for it before connecting: ```bash -docker logs -f docdb +timeout 180 bash -c 'until docker logs docdb 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done' \ + && echo "DocumentDB is ready" ``` -```output -=== DocumentDB is ready === -``` +First start typically takes a few tens of seconds. If the wait times out, the container most likely exited during startup - check `docker ps -a` and `docker logs docdb` for the error. -First start typically takes a few tens of seconds. +> Use `docker logs docdb` rather than `docker logs -f docdb` to check readiness. The container streams the PostgreSQL, gateway, and entrypoint logs to stdout for its whole lifetime, so `-f` never returns. + +### Connect with mongosh > The DocumentDB gateway endpoint is available on port `10260` by default. To access this with `mongosh`, run: @@ -79,24 +80,37 @@ The following table summarizes the available Docker commands for configuring the | Requirement | Arg | Env | Allowed values | Default | Description | |---|---|---|---|---|---| | Print the settings to stdout from the container | `--help`, `-h` | N/A | N/A | N/A | Display information on available configuration | -| Specify the username for DocumentDB. | `--username [value]` | Overrides `USERNAME` environment variable | STRING | `default_user` | Username for DocumentDB. | +| Specify the username for DocumentDB. | `--username [value]` | Overrides `USERNAME` environment variable | STRING | `default_user` | Username for DocumentDB. It may not be an internal DocumentDB role name, and it may not begin with `documentdb`, `citus`, `pg`, or `internal_role` (case-insensitive). The container rejects a reserved name and exits before starting anything. | | Specify the password for DocumentDB. | `--password [value]` | Overrides `PASSWORD` environment variable | STRING | `Admin100` | Password for DocumentDB. Always set this explicitly. The built-in default is well known, and anyone who can reach the published port can authenticate with it. | | The port of the DocumentDB endpoint. | `--documentdb-port [value]` | Overrides `DOCUMENTDB_PORT` environment variable | INT | `10260` | The port needs to be published - for example, using `-p 10260:10260`. | -| Specify a directory for data. | `--data-path [value]` | Overrides `DATA_PATH` environment variable. | STRING | `/data` | Data is not persisted unless you mount a volume at this path - for example, `-v documentdb-data:/data`. To use a different directory, set the flag and the mount together: `--data-path /usr/documentdb/data` with `--mount type=bind,source=./.local/data,target=/usr/documentdb/data`. | -| Specify the owner. | `--owner [value]` | Overrides `OWNER` environment variable. | STRING | `documentdb` | Specify the owner for DocumentDB. | +| Specify a directory for data. | `--data-path [value]` | Overrides `DATA_PATH` environment variable. | STRING | `/data` | Data is not persisted unless you mount a volume at this path - for example, `-v documentdb-data:/data`. To use a different directory, set the mount and the flag together, keeping in mind that they go on opposite sides of the image name: `-v` / `--mount` is a `docker run` option and comes before it, `--data-path` is a container argument and comes after it. See the example below the table. | +| Specify the owner. | `--owner [value]` | Overrides `OWNER` environment variable. | STRING | `documentdb` | The PostgreSQL role used to create the admin user. This image ships only the `documentdb` superuser, so leave it at the default: any other value fails with `role "" does not exist` after PostgreSQL has already initialized, and the container exits. | | Specify whether to start the PostgreSQL server. | `--start-pg [value]` | Overrides `START_POSTGRESQL` environment variable | `true`, `false` | `true` | Specify whether to start the PostgreSQL server. | | Specify whether to create a user. | `--create-user [value]` | Overrides `CREATE_USER` environment variable | `true`, `false` | `true` | Specify whether to create a user. | | Specify the port for the PostgreSQL server. | `--pg-port [value]` | Overrides `POSTGRESQL_PORT` environment variable | INT | `9712` | Specify the port for the PostgreSQL server. | -| Specify whether to allow external connections to PostgreSQL. | `--allow-external-connections [value]` | Overrides `ALLOW_EXTERNAL_CONNECTIONS` environment variable | `true`, `false` | `false` | Opens the container's internal PostgreSQL server to all interfaces. This does not affect the gateway, which always listens on all interfaces on the DocumentDB port. | +| Specify whether to allow external connections to PostgreSQL. | `--allow-external-connections [value]` | Overrides `ALLOW_EXTERNAL_CONNECTIONS` environment variable | `true`, `false` | `false` | Opens the container's internal PostgreSQL server to all interfaces and adds a permissive host-based authentication rule (`host all all 0.0.0.0/0 scram-sha-256`), which lets any role reach any database from any address with a password. It only changes configuration inside the container, so you also need to publish the PostgreSQL port - for example `-p 9712:9712` - to connect from the host. Ignored when `--start-pg false`. This does not affect the gateway, which always listens on all interfaces on the DocumentDB port. | | Specify the path to a certificate for securing traffic. | `--cert-path [value]` | Overrides `CERT_PATH` environment variable. | STRING | NA | PEM-format certificate. Must be set together with `--key-file` - setting only one of the two fails at startup. You need to mount this file into the container. For example, to set `/mycert.pem`, add this option to `docker run` command: `--mount type=bind,source=./mycert.pem,target=/mycert.pem`. | | Override default key with key in key file. | `--key-file [value]` | Overrides `KEY_FILE` environment variable. | STRING | NA | PEM-format private key. Must be set together with `--cert-path` - setting only one of the two fails at startup. You need to mount this file into the container. For example, to set `/mykey.key`, add this option to `docker run` command: `--mount type=bind,source=./mykey.key,target=/mykey.key` | | Set the TLS mode for client connections. | `--tlsMode [value]` | Overrides `TLS_MODE` environment variable | `disabled`, `allowTLS`, `requireTLS` | `allowTLS` | With `allowTLS` the gateway accepts both plain and TLS connections; `disabled` behaves the same way. `requireTLS` rejects plain connections, so every client must connect with `tls=true`. | | Enable initialization with built-in sample data. | `--init-data [value]` | Overrides `INIT_DATA` environment variable | `true`, `false` | `false` | Seeded once per data volume, on a fresh volume. Re-create the volume to seed again. | | Specify a directory of scripts for database initialization. | `--init-data-path [value]` | Overrides `INIT_DATA_PATH` environment variable | STRING | `/init_doc_db.d` | JavaScript files are executed in alphabetical order using `mongosh`, once per fresh data volume. Scripts should be idempotent - a failed run is not retried on restart. | -| Skip initialization with built-in sample data. | `--skip-init-data` | Overrides `SKIP_INIT_DATA` environment variable | N/A | N/A | Legacy alias for `--init-data false`. Does not affect `--init-data-path`. | -| Disable the use of extended RUM for indexes. | `--disable-extended-rum` | Overrides `DISABLE_EXTENDED_RUM` environment variable | N/A | `false` | Extended RUM is enabled by default. | -| Enable telemetry data. | `--enable-telemetry [value]` | Overrides `ENABLE_TELEMETRY` environment variable | `true`, `false` | `false` | Enable telemetry data sent to the usage collector. | -| Specify log verbosity. | `--log-level [value]` | Overrides `LOG_LEVEL` environment variable. | `quiet`, `error`, `warn`, `info`, `debug`, `trace` | `info` | The verbosity of logs that will be emitted. To set the gateway's own log level, use the `DOCUMENTDB_LOG_LEVEL` environment variable. | +| Skip initialization with built-in sample data. | `--skip-init-data` | Overrides `SKIP_INIT_DATA` environment variable | `true`, `false` (`SKIP_INIT_DATA` only - the flag itself takes no value) | N/A | Legacy alias for `--init-data false`. Note that `SKIP_INIT_DATA=false` does the opposite of the flag: with `INIT_DATA` unset it enables the built-in sample data. Does not affect `--init-data-path`. | +| Disable the use of extended RUM for indexes. | `--disable-extended-rum` | Overrides `DISABLE_EXTENDED_RUM` environment variable | N/A (takes no value) | N/A | Extended RUM is enabled by default. **Known issue:** this flag does not currently disable it - the container still starts with `documentdb_extended_rum` configured. | +| Enable telemetry data. | `--enable-telemetry [value]` | Overrides `ENABLE_TELEMETRY` environment variable | `true`, `false` | `false` | **Known issue:** the value is validated at startup but no telemetry is currently emitted - the gateway's metrics and tracing exporters are disabled in this image, and an invalid value only serves to abort startup. | +| Specify log verbosity. | `--log-level [value]` | Overrides `LOG_LEVEL` environment variable. | `quiet`, `error`, `warn`, `info`, `debug`, `trace` | `info` | **Known issue:** the value is validated at startup but does not currently change what the container logs. To change the gateway's own verbosity, set the `DOCUMENTDB_LOG_LEVEL` environment variable instead; it takes a tracing filter such as `info` or `debug` (`quiet` is not one of its values). | + +> `--skip-init-data` and `--disable-extended-rum` are the only options that take no value. Passing one anyway - for example `--disable-extended-rum false` - leaves the container spinning in its argument parser: it produces no logs, never becomes ready, and never exits. + +A complete `docker run` showing where each kind of option goes - Docker options before the image name, container arguments after it. This is the command from [Running](#running) with a persistent volume and sample data added, so remove that container first with `docker rm -f docdb`: + +```bash +docker run -dt \ + -p 10260:10260 \ + -v documentdb-data:/data \ + --name docdb \ + ghcr.io/documentdb/documentdb/documentdb-local:latest \ + --username demo --password test --init-data true +``` ## Feature support @@ -106,31 +120,26 @@ Please refer to the [documentdb](https://documentdb.io/docs/) documentation for ## Installing certificates -If you do not supply your own certificate with `--cert-path` and `--key-file`, DocumentDB Local generates a self-signed certificate on first start and reuses it on subsequent starts, so the certificate stays stable across restarts. To prevent certificate errors, install it on your local machine. The example below shows how to use this setup with `mongosh`. - -### Get certificate +If you do not supply your own certificate with `--cert-path` and `--key-file`, DocumentDB Local generates a self-signed certificate on first start and reuses it on subsequent starts of the same container, so `docker stop` / `docker start` keeps it stable. Removing and re-creating the container generates a new certificate unless you persist the directory it is stored in. The generated certificate is valid for 365 days and is not renewed automatically - re-create the container, or delete the files below, to generate a fresh one. -The gateway chooses where to store auto-generated TLS material based on which directories are writable, so pin the location with `DOCUMENTDB_TLS_STATE_DIR` when starting the container: +To validate the certificate instead of skipping validation with `tlsAllowInvalidCertificates=true`, copy it out of the container and point `mongosh` at it. -```bash -docker run -dt -p 10260:10260 --name docdb \ - -e DOCUMENTDB_TLS_STATE_DIR=/data/tls \ - ghcr.io/documentdb/documentdb/documentdb-local:latest --username demo --password test -``` +### Get certificate -In a `bash` window, run the following to copy the certificate from the container to the local -host: +The gateway picks its TLS state directory from the first writable candidate. In this image that resolves to a path under the container user's home directory, so no extra options are needed on the `docker run` above. In a `bash` window, copy the certificate from the container to the local host: ```bash -docker cp docdb:/data/tls/cert.pem ~/documentdb-cert.pem +docker cp docdb:/home/documentdb/.local/state/documentdb-gateway/tls/cert.pem ~/documentdb-cert.pem ``` -If you did not set `DOCUMENTDB_TLS_STATE_DIR`, the gateway logs the path it chose on startup: +The gateway logs the path it actually chose on startup. Check there first if the copy reports `No such container:path`: ```bash docker logs docdb | grep "TLS auto-gen" ``` +To pin the location yourself - for example on a mounted volume, so the certificate survives re-creating the container - set `DOCUMENTDB_TLS_STATE_DIR` when you first start the container, and point it somewhere outside `--data-path`. The entrypoint runs `chmod -R 750` over the data directory on every start, which would loosen the private key's permissions on each restart. + ### Use the certificate with mongosh ```bash diff --git a/getting-started/mongo-shell-quickstart.md b/getting-started/mongo-shell-quickstart.md index 0169c59..d33103c 100644 --- a/getting-started/mongo-shell-quickstart.md +++ b/getting-started/mongo-shell-quickstart.md @@ -15,7 +15,7 @@ Get started with DocumentDB using the MongoDB shell (`mongosh`) for a familiar M ## Setting up DocumentDB locally -Pull the latest `documentdb-local` image and start the container. DocumentDB Local listens on port `10260` by default and requires the username and password to be set on first run. +Pull the latest `documentdb-local` image and start the container. DocumentDB Local listens on port `10260` by default. Always set the username and password on first run - the container falls back to well-known built-in defaults otherwise. ```bash # Pull the latest DocumentDB Docker image @@ -28,7 +28,7 @@ docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb docker run -dt -p 10260:10260 --name documentdb-container documentdb --username --password ``` -> **Note:** Replace `` and `` with your desired credentials. These must be set when creating the container for authentication to work. +> **Note:** Replace `` and `` with your desired credentials. Always set them explicitly: if you omit them the container starts with the built-in `default_user` / `Admin100`, which are public and let anyone who can reach the published port authenticate as the admin user. > > **Port note:** Port `10260` is used by default to avoid conflicts with other local database services. You can use port `27017` (the standard MongoDB port) or any other available port — update the port in the `docker run` command and your connection string accordingly. @@ -38,9 +38,15 @@ Confirm the container is running: docker ps ``` +`docker ps` reports the container as `Up` before DocumentDB can accept connections, so wait for the ready banner before connecting: + +```bash +timeout 180 bash -c 'until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done' +``` + ## Connecting to DocumentDB -DocumentDB Local terminates TLS on the gateway port. The container generates a self-signed certificate on first start and reuses it thereafter, so the simplest local connection skips certificate validation with `tlsAllowInvalidCertificates=true`. +DocumentDB Local accepts TLS connections on the gateway port and requires authentication. The container generates a self-signed certificate on first start and reuses it thereafter, so the simplest local connection skips certificate validation with `tlsAllowInvalidCertificates=true`. ```bash mongosh "mongodb://:@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true" diff --git a/getting-started/nodejs-setup.md b/getting-started/nodejs-setup.md index 482e9f4..443394a 100644 --- a/getting-started/nodejs-setup.md +++ b/getting-started/nodejs-setup.md @@ -32,7 +32,9 @@ Before connecting from Node.js, make sure you have a running DocumentDB instance ``` > **Note:** During the transition to the Linux Foundation, Docker images may still be hosted on Microsoft's container registry. These will be migrated to the new DocumentDB organization as the transition completes. > -> **Note:** Replace `` and `` with your desired credentials. You must set these when creating the container for authentication to work. +> **Note:** Replace `` and `` with your desired credentials. Always set them explicitly: if you omit them the container starts with the built-in `default_user` / `Admin100`, which are public and let anyone who can reach the published port authenticate as the admin user. +> +> **Readiness Note:** `docker ps` reports the container as `Up` before DocumentDB can accept connections. Wait for the ready banner first: `timeout 180 bash -c 'until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done'` > > **Port Note:** Port `10260` is used by default in these instructions to avoid conflicts with other local database services. You can use port `27017` (the standard MongoDB port) or any other available port if you prefer. If you do, be sure to update the port number in both your `docker run` command and your connection string accordingly. @@ -52,7 +54,7 @@ Before connecting from Node.js, make sure you have a running DocumentDB instance ## Connecting to DocumentDB -DocumentDB Local requires TLS and authentication on the gateway port. Connect with the username and password you set when starting the container, and because the container uses a self-signed certificate, the simplest local setup skips certificate validation with `tlsAllowInvalidCertificates=true` (in production, provide the gateway certificate instead). +DocumentDB Local accepts TLS connections on the gateway port and requires authentication. Connect with the username and password you set when starting the container, and because the container uses a self-signed certificate, the simplest local setup skips certificate validation with `tlsAllowInvalidCertificates=true` (in production, provide the gateway certificate instead). ```javascript const { MongoClient } = require('mongodb'); diff --git a/getting-started/python-setup.md b/getting-started/python-setup.md index 05d53ee..f23beca 100644 --- a/getting-started/python-setup.md +++ b/getting-started/python-setup.md @@ -42,13 +42,15 @@ Learn how to set up and use DocumentDB with Python using the official MongoDB Py docker image rm -f ghcr.io/documentdb/documentdb/documentdb-local:latest ``` > **Note:** During the transition to the Linux Foundation, Docker images may still be hosted on Microsoft's container registry. These will be migrated to the new DocumentDB organization as the transition completes. - > **Note:** Replace `` and `` with your desired credentials. You must set these when creating the container for authentication to work. + > **Note:** Replace `` and `` with your desired credentials. Always set them explicitly: if you omit them the container starts with the built-in `default_user` / `Admin100`, which are public and let anyone who can reach the published port authenticate as the admin user. + > + > **Readiness Note:** `docker ps` reports the container as `Up` before DocumentDB can accept connections. Wait for the ready banner first: `timeout 180 bash -c 'until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done'` > > **Port Note:** Port `10260` is used by default in these instructions to avoid conflicts with other local database services. You can use port `27017` (the standard MongoDB port) or any other available port if you prefer. If you do, be sure to update the port number in both your `docker run` command and your connection string accordingly. ## Connecting to DocumentDB -DocumentDB Local requires TLS and authentication on the gateway port. Connect with the username and password you set when starting the container, and because the container uses a self-signed certificate, the simplest local setup skips certificate validation with `tlsAllowInvalidCertificates=true` (in production, provide the gateway certificate instead). +DocumentDB Local accepts TLS connections on the gateway port and requires authentication. Connect with the username and password you set when starting the container, and because the container uses a self-signed certificate, the simplest local setup skips certificate validation with `tlsAllowInvalidCertificates=true` (in production, provide the gateway certificate instead). 1. Basic Connection ```python diff --git a/postgres-api/configuration.md b/postgres-api/configuration.md index 2f0b8a9..c04823c 100644 --- a/postgres-api/configuration.md +++ b/postgres-api/configuration.md @@ -40,7 +40,7 @@ The gateway (`pg_documentdb_gw`) reads its settings from a JSON configuration fi | `DOCUMENTDB_TLS_CERT_FILE` | Path to the TLS certificate file. | | `DOCUMENTDB_TLS_KEY_FILE` | Path to the TLS private key file. | | `DOCUMENTDB_TLS_AUTO_GENERATE` | When `true`, auto-generate a self-signed certificate if no cert/key files are provided. | -| `DOCUMENTDB_TLS_STATE_DIR` | Directory where an auto-generated certificate/key is written and re-read on restart (defaults to `/var/lib/documentdb-gateway/tls`). | +| `DOCUMENTDB_TLS_STATE_DIR` | Directory where an auto-generated certificate/key is written and re-read on restart (defaults to `/var/lib/documentdb-gateway/tls`). When that directory is not writable — as in the `documentdb-local` container image — the gateway falls back to a per-user state directory under `$HOME/.local/state` and logs the path it chose. | | `DOCUMENTDB_LOG_LEVEL` | Log level for the gateway's tracing subscriber (for example `info`, `debug`). | For systemd-managed installs these are typically set through the unit's `EnvironmentFile` (for example `gateway.env`). From 01faed24abd506a9bbc3f3aed8796f85630586d3 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Mon, 3 Aug 2026 12:30:27 -0400 Subject: [PATCH 3/6] Refine readiness command portability and certificate persistence guidance - 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. --- documentdb-local/index.md | 25 ++++++++++++++++------- getting-started/mongo-shell-quickstart.md | 4 +++- getting-started/nodejs-setup.md | 2 +- getting-started/python-setup.md | 2 +- 4 files changed, 23 insertions(+), 10 deletions(-) diff --git a/documentdb-local/index.md b/documentdb-local/index.md index f631c77..0bf363a 100644 --- a/documentdb-local/index.md +++ b/documentdb-local/index.md @@ -45,11 +45,10 @@ CONTAINER ID IMAGE The entrypoint prints a ready banner once the gateway is accepting connections. Wait for it before connecting: ```bash -timeout 180 bash -c 'until docker logs docdb 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done' \ - && echo "DocumentDB is ready" +until docker logs docdb 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done ``` -First start typically takes a few tens of seconds. If the wait times out, the container most likely exited during startup - check `docker ps -a` and `docker logs docdb` for the error. +First start typically takes a few tens of seconds. If the command has not returned after a couple of minutes, the container most likely exited during startup - interrupt it and check `docker ps -a` and `docker logs docdb` for the error. > Use `docker logs docdb` rather than `docker logs -f docdb` to check readiness. The container streams the PostgreSQL, gateway, and entrypoint logs to stdout for its whole lifetime, so `-f` never returns. @@ -84,7 +83,7 @@ The following table summarizes the available Docker commands for configuring the | Specify the password for DocumentDB. | `--password [value]` | Overrides `PASSWORD` environment variable | STRING | `Admin100` | Password for DocumentDB. Always set this explicitly. The built-in default is well known, and anyone who can reach the published port can authenticate with it. | | The port of the DocumentDB endpoint. | `--documentdb-port [value]` | Overrides `DOCUMENTDB_PORT` environment variable | INT | `10260` | The port needs to be published - for example, using `-p 10260:10260`. | | Specify a directory for data. | `--data-path [value]` | Overrides `DATA_PATH` environment variable. | STRING | `/data` | Data is not persisted unless you mount a volume at this path - for example, `-v documentdb-data:/data`. To use a different directory, set the mount and the flag together, keeping in mind that they go on opposite sides of the image name: `-v` / `--mount` is a `docker run` option and comes before it, `--data-path` is a container argument and comes after it. See the example below the table. | -| Specify the owner. | `--owner [value]` | Overrides `OWNER` environment variable. | STRING | `documentdb` | The PostgreSQL role used to create the admin user. This image ships only the `documentdb` superuser, so leave it at the default: any other value fails with `role "" does not exist` after PostgreSQL has already initialized, and the container exits. | +| Specify the owner. | `--owner [value]` | Overrides `OWNER` environment variable. | STRING | `documentdb` | The PostgreSQL role used to create the admin user. The cluster this image initializes has a single superuser role, `documentdb`, so leave this at the default: any other value fails with `role "" does not exist` after PostgreSQL has already initialized, and the container exits. | | Specify whether to start the PostgreSQL server. | `--start-pg [value]` | Overrides `START_POSTGRESQL` environment variable | `true`, `false` | `true` | Specify whether to start the PostgreSQL server. | | Specify whether to create a user. | `--create-user [value]` | Overrides `CREATE_USER` environment variable | `true`, `false` | `true` | Specify whether to create a user. | | Specify the port for the PostgreSQL server. | `--pg-port [value]` | Overrides `POSTGRESQL_PORT` environment variable | INT | `9712` | Specify the port for the PostgreSQL server. | @@ -120,13 +119,13 @@ Please refer to the [documentdb](https://documentdb.io/docs/) documentation for ## Installing certificates -If you do not supply your own certificate with `--cert-path` and `--key-file`, DocumentDB Local generates a self-signed certificate on first start and reuses it on subsequent starts of the same container, so `docker stop` / `docker start` keeps it stable. Removing and re-creating the container generates a new certificate unless you persist the directory it is stored in. The generated certificate is valid for 365 days and is not renewed automatically - re-create the container, or delete the files below, to generate a fresh one. +If you do not supply your own certificate with `--cert-path` and `--key-file`, DocumentDB Local generates a self-signed certificate on first start and reuses it on subsequent starts of the same container, so `docker stop` / `docker start` keeps it stable. Removing and re-creating the container generates a new certificate unless you persist the directory it is stored in. The generated certificate is valid for 365 days and is not renewed automatically - re-create the container, or delete `cert.pem` from the state directory shown below, to generate a fresh one. To validate the certificate instead of skipping validation with `tlsAllowInvalidCertificates=true`, copy it out of the container and point `mongosh` at it. ### Get certificate -The gateway picks its TLS state directory from the first writable candidate. In this image that resolves to a path under the container user's home directory, so no extra options are needed on the `docker run` above. In a `bash` window, copy the certificate from the container to the local host: +The gateway picks its TLS state directory from the first writable candidate. In this image that resolves to a path under the container user's home directory, so no extra options are needed when starting the container. In a `bash` window, copy the certificate from the container to the local host: ```bash docker cp docdb:/home/documentdb/.local/state/documentdb-gateway/tls/cert.pem ~/documentdb-cert.pem @@ -138,7 +137,19 @@ The gateway logs the path it actually chose on startup. Check there first if the docker logs docdb | grep "TLS auto-gen" ``` -To pin the location yourself - for example on a mounted volume, so the certificate survives re-creating the container - set `DOCUMENTDB_TLS_STATE_DIR` when you first start the container, and point it somewhere outside `--data-path`. The entrypoint runs `chmod -R 750` over the data directory on every start, which would loosen the private key's permissions on each restart. +To keep the same certificate across re-creating the container, pin the location with `DOCUMENTDB_TLS_STATE_DIR` and put it inside the data volume: + +```bash +docker run -dt \ + -p 10260:10260 \ + -v documentdb-data:/data \ + -e DOCUMENTDB_TLS_STATE_DIR=/data/tls \ + --name docdb \ + ghcr.io/documentdb/documentdb/documentdb-local:latest \ + --username demo --password test +``` + +Point it inside the data directory rather than at a volume of its own: the entrypoint takes ownership of the data directory on every start, whereas a separate volume is created root-owned and the gateway - which runs as an unprivileged user - cannot write its key there. The trade-off is that the same step runs `chmod -R 750` over that directory, so from the second start onwards the private key is group-readable rather than owner-only, and it is included in any backup of the data volume. ### Use the certificate with mongosh diff --git a/getting-started/mongo-shell-quickstart.md b/getting-started/mongo-shell-quickstart.md index d33103c..2fb8ed2 100644 --- a/getting-started/mongo-shell-quickstart.md +++ b/getting-started/mongo-shell-quickstart.md @@ -41,9 +41,11 @@ docker ps `docker ps` reports the container as `Up` before DocumentDB can accept connections, so wait for the ready banner before connecting: ```bash -timeout 180 bash -c 'until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done' +until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done ``` +If this has not returned after a couple of minutes, the container probably exited during startup - interrupt it and check `docker logs documentdb-container`. + ## Connecting to DocumentDB DocumentDB Local accepts TLS connections on the gateway port and requires authentication. The container generates a self-signed certificate on first start and reuses it thereafter, so the simplest local connection skips certificate validation with `tlsAllowInvalidCertificates=true`. diff --git a/getting-started/nodejs-setup.md b/getting-started/nodejs-setup.md index 443394a..466285f 100644 --- a/getting-started/nodejs-setup.md +++ b/getting-started/nodejs-setup.md @@ -34,7 +34,7 @@ Before connecting from Node.js, make sure you have a running DocumentDB instance > > **Note:** Replace `` and `` with your desired credentials. Always set them explicitly: if you omit them the container starts with the built-in `default_user` / `Admin100`, which are public and let anyone who can reach the published port authenticate as the admin user. > -> **Readiness Note:** `docker ps` reports the container as `Up` before DocumentDB can accept connections. Wait for the ready banner first: `timeout 180 bash -c 'until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done'` +> **Readiness Note:** `docker ps` reports the container as `Up` before DocumentDB can accept connections. Wait for the ready banner first: `until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done` > > **Port Note:** Port `10260` is used by default in these instructions to avoid conflicts with other local database services. You can use port `27017` (the standard MongoDB port) or any other available port if you prefer. If you do, be sure to update the port number in both your `docker run` command and your connection string accordingly. diff --git a/getting-started/python-setup.md b/getting-started/python-setup.md index f23beca..15d7291 100644 --- a/getting-started/python-setup.md +++ b/getting-started/python-setup.md @@ -44,7 +44,7 @@ Learn how to set up and use DocumentDB with Python using the official MongoDB Py > **Note:** During the transition to the Linux Foundation, Docker images may still be hosted on Microsoft's container registry. These will be migrated to the new DocumentDB organization as the transition completes. > **Note:** Replace `` and `` with your desired credentials. Always set them explicitly: if you omit them the container starts with the built-in `default_user` / `Admin100`, which are public and let anyone who can reach the published port authenticate as the admin user. > - > **Readiness Note:** `docker ps` reports the container as `Up` before DocumentDB can accept connections. Wait for the ready banner first: `timeout 180 bash -c 'until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done'` + > **Readiness Note:** `docker ps` reports the container as `Up` before DocumentDB can accept connections. Wait for the ready banner first: `until docker logs documentdb-container 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done` > > **Port Note:** Port `10260` is used by default in these instructions to avoid conflicts with other local database services. You can use port `27017` (the standard MongoDB port) or any other available port if you prefer. If you do, be sure to update the port number in both your `docker run` command and your connection string accordingly. From 629286fb50d23a2a4d33b810a299b5d7b7d8fa19 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Mon, 3 Aug 2026 12:31:07 -0400 Subject: [PATCH 4/6] Drop unproven in-page anchor; document --start-pg / --create-user effects 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. --- documentdb-local/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentdb-local/index.md b/documentdb-local/index.md index 0bf363a..6940d1a 100644 --- a/documentdb-local/index.md +++ b/documentdb-local/index.md @@ -84,8 +84,8 @@ The following table summarizes the available Docker commands for configuring the | The port of the DocumentDB endpoint. | `--documentdb-port [value]` | Overrides `DOCUMENTDB_PORT` environment variable | INT | `10260` | The port needs to be published - for example, using `-p 10260:10260`. | | Specify a directory for data. | `--data-path [value]` | Overrides `DATA_PATH` environment variable. | STRING | `/data` | Data is not persisted unless you mount a volume at this path - for example, `-v documentdb-data:/data`. To use a different directory, set the mount and the flag together, keeping in mind that they go on opposite sides of the image name: `-v` / `--mount` is a `docker run` option and comes before it, `--data-path` is a container argument and comes after it. See the example below the table. | | Specify the owner. | `--owner [value]` | Overrides `OWNER` environment variable. | STRING | `documentdb` | The PostgreSQL role used to create the admin user. The cluster this image initializes has a single superuser role, `documentdb`, so leave this at the default: any other value fails with `role "" does not exist` after PostgreSQL has already initialized, and the container exits. | -| Specify whether to start the PostgreSQL server. | `--start-pg [value]` | Overrides `START_POSTGRESQL` environment variable | `true`, `false` | `true` | Specify whether to start the PostgreSQL server. | -| Specify whether to create a user. | `--create-user [value]` | Overrides `CREATE_USER` environment variable | `true`, `false` | `true` | Specify whether to create a user. | +| Specify whether to start the PostgreSQL server. | `--start-pg [value]` | Overrides `START_POSTGRESQL` environment variable | `true`, `false` | `true` | Set this to `false` only when you are pointing the gateway at a PostgreSQL server you run yourself; the container then expects one to be reachable on `--pg-port`. | +| Specify whether to create a user. | `--create-user [value]` | Overrides `CREATE_USER` environment variable | `true`, `false` | `true` | With `false` the container starts the gateway without creating the admin user, so `--username` and `--password` have no effect and no client can authenticate until you create a user yourself. | | Specify the port for the PostgreSQL server. | `--pg-port [value]` | Overrides `POSTGRESQL_PORT` environment variable | INT | `9712` | Specify the port for the PostgreSQL server. | | Specify whether to allow external connections to PostgreSQL. | `--allow-external-connections [value]` | Overrides `ALLOW_EXTERNAL_CONNECTIONS` environment variable | `true`, `false` | `false` | Opens the container's internal PostgreSQL server to all interfaces and adds a permissive host-based authentication rule (`host all all 0.0.0.0/0 scram-sha-256`), which lets any role reach any database from any address with a password. It only changes configuration inside the container, so you also need to publish the PostgreSQL port - for example `-p 9712:9712` - to connect from the host. Ignored when `--start-pg false`. This does not affect the gateway, which always listens on all interfaces on the DocumentDB port. | | Specify the path to a certificate for securing traffic. | `--cert-path [value]` | Overrides `CERT_PATH` environment variable. | STRING | NA | PEM-format certificate. Must be set together with `--key-file` - setting only one of the two fails at startup. You need to mount this file into the container. For example, to set `/mycert.pem`, add this option to `docker run` command: `--mount type=bind,source=./mycert.pem,target=/mycert.pem`. | @@ -100,7 +100,7 @@ The following table summarizes the available Docker commands for configuring the > `--skip-init-data` and `--disable-extended-rum` are the only options that take no value. Passing one anyway - for example `--disable-extended-rum false` - leaves the container spinning in its argument parser: it produces no logs, never becomes ready, and never exits. -A complete `docker run` showing where each kind of option goes - Docker options before the image name, container arguments after it. This is the command from [Running](#running) with a persistent volume and sample data added, so remove that container first with `docker rm -f docdb`: +A complete `docker run` showing where each kind of option goes - Docker options before the image name, container arguments after it. This is the command from the **Running** section above with a persistent volume and sample data added, so remove that container first with `docker rm -f docdb`: ```bash docker run -dt \ From 569c137f8458de7dbf3b2f24013075869b7fcc3e Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Mon, 3 Aug 2026 12:31:30 -0400 Subject: [PATCH 5/6] Tighten --create-user description --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". --- documentdb-local/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentdb-local/index.md b/documentdb-local/index.md index 6940d1a..7776074 100644 --- a/documentdb-local/index.md +++ b/documentdb-local/index.md @@ -85,7 +85,7 @@ The following table summarizes the available Docker commands for configuring the | Specify a directory for data. | `--data-path [value]` | Overrides `DATA_PATH` environment variable. | STRING | `/data` | Data is not persisted unless you mount a volume at this path - for example, `-v documentdb-data:/data`. To use a different directory, set the mount and the flag together, keeping in mind that they go on opposite sides of the image name: `-v` / `--mount` is a `docker run` option and comes before it, `--data-path` is a container argument and comes after it. See the example below the table. | | Specify the owner. | `--owner [value]` | Overrides `OWNER` environment variable. | STRING | `documentdb` | The PostgreSQL role used to create the admin user. The cluster this image initializes has a single superuser role, `documentdb`, so leave this at the default: any other value fails with `role "" does not exist` after PostgreSQL has already initialized, and the container exits. | | Specify whether to start the PostgreSQL server. | `--start-pg [value]` | Overrides `START_POSTGRESQL` environment variable | `true`, `false` | `true` | Set this to `false` only when you are pointing the gateway at a PostgreSQL server you run yourself; the container then expects one to be reachable on `--pg-port`. | -| Specify whether to create a user. | `--create-user [value]` | Overrides `CREATE_USER` environment variable | `true`, `false` | `true` | With `false` the container starts the gateway without creating the admin user, so `--username` and `--password` have no effect and no client can authenticate until you create a user yourself. | +| Specify whether to create a user. | `--create-user [value]` | Overrides `CREATE_USER` environment variable | `true`, `false` | `true` | With `false` the container starts the gateway without creating the admin user. Nothing can authenticate with `--username` / `--password` until you create a user yourself, and data initialization fails if you enabled it. | | Specify the port for the PostgreSQL server. | `--pg-port [value]` | Overrides `POSTGRESQL_PORT` environment variable | INT | `9712` | Specify the port for the PostgreSQL server. | | Specify whether to allow external connections to PostgreSQL. | `--allow-external-connections [value]` | Overrides `ALLOW_EXTERNAL_CONNECTIONS` environment variable | `true`, `false` | `false` | Opens the container's internal PostgreSQL server to all interfaces and adds a permissive host-based authentication rule (`host all all 0.0.0.0/0 scram-sha-256`), which lets any role reach any database from any address with a password. It only changes configuration inside the container, so you also need to publish the PostgreSQL port - for example `-p 9712:9712` - to connect from the host. Ignored when `--start-pg false`. This does not affect the gateway, which always listens on all interfaces on the DocumentDB port. | | Specify the path to a certificate for securing traffic. | `--cert-path [value]` | Overrides `CERT_PATH` environment variable. | STRING | NA | PEM-format certificate. Must be set together with `--key-file` - setting only one of the two fails at startup. You need to mount this file into the container. For example, to set `/mycert.pem`, add this option to `docker run` command: `--mount type=bind,source=./mycert.pem,target=/mycert.pem`. | From 0b431bf5916dd1f00acfe871b0cc346fe95e34c9 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Mon, 3 Aug 2026 12:31:47 -0400 Subject: [PATCH 6/6] Note the teardown step before the TLS-state-dir example 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. --- documentdb-local/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentdb-local/index.md b/documentdb-local/index.md index 7776074..d11203d 100644 --- a/documentdb-local/index.md +++ b/documentdb-local/index.md @@ -137,7 +137,7 @@ The gateway logs the path it actually chose on startup. Check there first if the docker logs docdb | grep "TLS auto-gen" ``` -To keep the same certificate across re-creating the container, pin the location with `DOCUMENTDB_TLS_STATE_DIR` and put it inside the data volume: +To keep the same certificate across re-creating the container, pin the location with `DOCUMENTDB_TLS_STATE_DIR` and put it inside the data volume. This replaces the container you started earlier, so run `docker rm -f docdb` first: ```bash docker run -dt \