|
| 1 | +# DocumentDB-local |
| 2 | +DocumentDB is available as a Docker container. It supports running on a wide variety of processors and operating systems and make it easy to try out and test DocumentDB. |
| 3 | + |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- [Docker](https://www.docker.com/) |
| 8 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +Get the Docker container image using `docker pull`. The container image is published to the Github container registry as `ghcr.io/documentdb/documentdb/documentdb-local:latest`. |
| 12 | + |
| 13 | +```bash |
| 14 | +docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest |
| 15 | + |
| 16 | +``` |
| 17 | + |
| 18 | +## Running |
| 19 | + |
| 20 | +To run the container, use `docker run`. Afterwards, use `docker ps` to validate that the container is running. |
| 21 | + |
| 22 | +```bash |
| 23 | +docker run -dt -p 10260:10260 --name docdb ghcr.io/documentdb/documentdb/documentdb-local:latest --username demo --password test |
| 24 | + |
| 25 | + |
| 26 | +docker ps |
| 27 | +``` |
| 28 | + |
| 29 | +```output |
| 30 | +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES |
| 31 | +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 |
| 32 | +``` |
| 33 | + |
| 34 | +> The DocumenttDB Mongo protocol gateway endpoint is typically available on port `10260`. To access this with `mongosh` run: |
| 35 | +
|
| 36 | +```bash |
| 37 | +mongosh "mongodb://demo:test@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true" |
| 38 | +``` |
| 39 | + |
| 40 | +```output |
| 41 | +Current Mongosh Log ID: 690cdcb84e2e610f0f48e609 |
| 42 | +Connecting to: mongodb://<credentials>@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true&directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.5.1 |
| 43 | +Using MongoDB: 7.0.0 |
| 44 | +Using Mongosh: 2.5.1 |
| 45 | +mongosh 2.5.9 is available for download: https://www.mongodb.com/try/download/shell |
| 46 | +
|
| 47 | +For mongosh info see: https://www.mongodb.com/docs/mongodb-shell/ |
| 48 | +
|
| 49 | +[direct: mongos] test> |
| 50 | +``` |
| 51 | + |
| 52 | +## Docker commands |
| 53 | + |
| 54 | +The following table summarizes the available Docker commands for configuring the emulator. This table details the corresponding arguments, environment variables, allowed values, default settings, and descriptions of each command. |
| 55 | + |
| 56 | +| Requirement | Arg | Env | Allowed values | Default | Description | |
| 57 | +|---|---|---|---|---|---| |
| 58 | +| Print the settings to stdout from the container | `--help`, `-h` | N/A | N/A | N/A | Display information on available configuration | |
| 59 | + |
| 60 | +To be continued... |
| 61 | +## Feature support |
| 62 | + |
| 63 | +Please refer to the documentdb documentation for currently supported features, |
| 64 | + |
| 65 | + |
| 66 | +## Limitations |
| 67 | + |
| 68 | +In addition to features not yet supported or not planned, the following list includes current limitations of docuemntdb-lcoal: |
| 69 | + |
| 70 | +To be added. |
| 71 | + |
| 72 | + |
| 73 | +## Installing certificates |
| 74 | + |
| 75 | +DocumentDB-local by default will generate new selef signed certificates each tome you start the container. To avoid certificate errors these can be installed on the local host. The example belw will show how to use this with `mongosh`. |
| 76 | + |
| 77 | +### Get certificate |
| 78 | + |
| 79 | +In a `bash` window, run the following to copy the certificate from the container to the local |
| 80 | +host: |
| 81 | + |
| 82 | +```bash |
| 83 | +docker cp docdb:/home/documentdb/gateway/pg_documentdb_gw/cert.pem ~/documentdb-cert.pem |
| 84 | +``` |
| 85 | + |
| 86 | +### Use the certificate with mongosh |
| 87 | + |
| 88 | +```bash |
| 89 | +mongosh localhost:10260 -u demo -p test --authenticationMechanism SCRAM-SHA-256 --tls --tlsCAFile ~/documentdb-cert.pem |
| 90 | +``` |
| 91 | + |
| 92 | +```output |
| 93 | +Current Mongosh Log ID: 690ce1171181053c6edbf354 |
| 94 | +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 |
| 95 | +Using MongoDB: 7.0.0 |
| 96 | +Using Mongosh: 2.5.1 |
| 97 | +mongosh 2.5.9 is available for download: https://www.mongodb.com/try/download/shell |
| 98 | +
|
| 99 | +For mongosh info see: https://www.mongodb.com/docs/mongodb-shell/ |
| 100 | +
|
| 101 | +[direct: mongos] test> |
| 102 | +``` |
| 103 | + |
| 104 | +## Use in continuous integration workflow |
| 105 | +TBD |
| 106 | + |
| 107 | +## Reporting issues |
| 108 | + |
| 109 | +If you encounter issues with using this version of DoucmenttDB, open an issue in the GitHub repository (<https://github.com/documentdb/documentdb/issues>) and tag it with the label `documentdb-local`. |
0 commit comments