documentdb · GuanzhouSong · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026 · Aug 3, 2026
diff --git 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 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`.
+
+The entrypoint prints a ready banner once the gateway is accepting connections. Wait for it before connecting:
+
+```bash
+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 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.
+
+### Connect with mongosh
+
 > The DocumentDB gateway endpoint is available on port `10260` by default. To access this with `mongosh`, run:
 
 ```bash
@@ -61,19 +79,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 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 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 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 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 "<value>" 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. 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` | 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 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 | `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 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 \
+  -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
@@ -83,17 +119,38 @@ 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 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
 
-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 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
+```
+
+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 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 cp docdb:/home/documentdb/gateway/pg_documentdb_gw/cert.pem ~/documentdb-cert.pem
+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
 
 ```bash
@@ -102,7 +159,7 @@ mongosh localhost:10260 -u demo -p test --authenticationMechanism SCRAM-SHA-256
 
 ```output
 Current Mongosh Log ID:	690ce1171181053c6edbf354
-Connecting to:		mongodb://<credentials>@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://<credentials>@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
@@ -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 <YOUR_USERNAME> --password <YOUR_PASSWORD>
 ```
 
-> **Note:** Replace `<YOUR_USERNAME>` and `<YOUR_PASSWORD>` with your desired credentials. These must be set when creating the container for authentication to work.
+> **Note:** Replace `<YOUR_USERNAME>` and `<YOUR_PASSWORD>` 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,17 @@ 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
+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 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 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://<YOUR_USERNAME>:<YOUR_PASSWORD>@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true"