Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

docs(docdb): document DocumentDB service (#1386)

Ahmed khaledd77f11abbbae
diff --git a/README.md b/README.md
index 4996b01836..318c80330a 100644
--- a/README.md
+++ b/README.md
@@ -173,6 +173,7 @@ LocalStack's community edition [sunset in March 2026](https://blog.localstack.cl
| Cognito | Yes | No |
| RDS, ElastiCache, MSK | Real Docker | No |
| Neptune (graph DB + Gremlin WebSocket) | Real Docker | No |
+| DocumentDB (MongoDB-compatible) | Real Docker | No |
| ECS, EC2, EKS | Real Docker | No |
| CodeBuild | Real Docker execution | No |
| Native binary | ~40 MB | No |
@@ -224,7 +225,7 @@ Floci supports local emulation for application services, data services, eventing
| Containers and compute | ECS, EC2, EKS, CodeBuild, CodeDeploy, Auto Scaling, ELB v2 |
| Data and analytics | Athena, Glue, EMR, Firehose, OpenSearch, Textract, Transcribe |
| Security and governance | WAF v2, CloudTrail |
-| Databases | RDS, RDS Data API, Neptune |
+| Databases | RDS, RDS Data API, Neptune, DocumentDB |
| Messaging and transfer | SES, SES v2, Kinesis, Transfer Family |
| Cost and billing | Pricing, Cost Explorer, Cost and Usage Reports, BCM Data Exports |
| Backup and config | AWS Backup, AWS Config, AppConfig, AppConfigData, CloudFormation |
@@ -264,6 +265,7 @@ For operation-level compatibility, see the [Services Overview](https://floci.io/
| RDS | Real Docker | PostgreSQL, MySQL, MariaDB, IAM auth, JDBC-compatible engines |
| RDS Data API | REST JSON over real RDS containers | Raw SQL execution and transactions for local MySQL / MariaDB RDS resources |
| Neptune | Real Docker | Graph DB via TinkerPop Gremlin Server; RDS-shaped control plane; Gremlin WebSocket on port 8182 with SigV4 proxy |
+| DocumentDB | Real Docker, mock mode available | MongoDB-compatible cluster via real MongoDB containers; RDS-shaped control plane; MongoDB wire protocol on port 27017 |
| MSK | Real Docker | Kafka-compatible broker via Redpanda |
| Athena | In-process with DuckDB sidecar | Real SQL execution over S3 and Glue-backed views |
| Glue | In-process | Data Catalog, Schema Registry, tables consumed by Athena |
@@ -313,6 +315,7 @@ Floci uses real Docker containers when in-process emulation would reduce fidelit
| RDS MySQL / Aurora | `mysql:8.0` | MySQL engine, IAM auth, JDBC-compatible access |
| RDS MariaDB | `mariadb:11` | MariaDB engine, IAM auth, JDBC-compatible access |
| Neptune | `tinkerpop/gremlin-server:3.7.3` | TinkerPop Gremlin Server; Gremlin WebSocket on port 8182; SigV4 auth proxy |
+| DocumentDB | `mongo:7.0` | MongoDB engine; MongoDB wire protocol on port 27017 |
| MSK | `redpandadata/redpanda:latest` | Kafka-compatible broker via Redpanda |
| EC2 | AMI-mapped Linux images | Linux containers, SSH key injection, UserData, IMDS, IAM credentials |
| ECS | User-specified task image | Container lifecycle, start, stop, health checks |
@@ -342,6 +345,7 @@ docker run -d --name floci \
| `FLOCI_SERVICES_MSK_DEFAULT_IMAGE` | `redpandadata/redpanda:latest` |
| `FLOCI_SERVICES_OPENSEARCH_DEFAULT_IMAGE` | `opensearchproject/opensearch:2` |
| `FLOCI_SERVICES_NEPTUNE_DEFAULT_IMAGE` | `tinkerpop/gremlin-server:3.7.3` |
+| `FLOCI_SERVICES_DOCDB_DEFAULT_IMAGE` | `mongo:7.0` |
| `FLOCI_SERVICES_EKS_DEFAULT_IMAGE` | `rancher/k3s:latest` |
| `FLOCI_SERVICES_ECR_REGISTRY_IMAGE` | `registry:2` |
| `FLOCI_ECR_BASE_URI` | `public.ecr.aws` |
diff --git a/docs/index.md b/docs/index.md
index 235aeba586..7543bbab9c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -38,6 +38,7 @@ Floci emulates 58 AWS services. See the [Services Overview](services/index.md) f
| RDS (PostgreSQL / MySQL) | Query + wire proxy |
| RDS Data API | REST JSON |
| Neptune (graph DB / Gremlin) | Query + WebSocket proxy |
+| DocumentDB (MongoDB-compatible) | Query + MongoDB wire |
| MSK (Kafka / Redpanda) | REST JSON + Kafka |
| Athena | JSON 1.1 |
| Glue Data Catalog + Schema Registry | JSON 1.1 |
diff --git a/docs/services/docdb.md b/docs/services/docdb.md
new file mode 100644
index 0000000000..025b1af734
--- /dev/null
+++ b/docs/services/docdb.md
@@ -0,0 +1,141 @@
+# DocumentDB
+
+**Protocol:** Query (XML) for the management API
+**Management Endpoint:** `POST http://localhost:4566/` with `Action=` param
+**Data Endpoint:** the `Endpoint` and `Port` returned by `DescribeDBClusters` (MongoDB wire protocol)
+
+Floci emulates Amazon DocumentDB by managing real [MongoDB](https://www.mongodb.com/) Docker containers behind an RDS-shaped control plane. DocumentDB is MongoDB-compatible, so the cluster endpoint returned by `DescribeDBClusters` speaks the MongoDB wire protocol and works with any standard MongoDB driver.
+
+> **Always read the host and port from `DescribeDBClusters`** rather than assuming a fixed port. MongoDB listens on `27017` *inside* the container, but the port you connect to depends on how Floci runs:
+>
+> - **Real mode, Floci on the host** (default): the container's `27017` is published on a **dynamically assigned host port**. `DescribeDBClusters.Port` returns that mapped port.
+> - **Real mode, Floci itself in a container** (shared Docker network): the endpoint is the container host on `27017`.
+> - **Mock mode** (`FLOCI_SERVICES_DOCDB_MOCK=true`): no container is started; the cluster reports `localhost:27017`.
+
+The management API shares the RDS Query endpoint (`POST /` with an `Action=` parameter). Requests are routed to DocumentDB when `Engine=docdb` is supplied, or when the referenced cluster/instance is a known DocumentDB resource.
+
+## Supported Actions
+
+| Action | Description |
+|--------|-------------|
+| `CreateDBCluster` | Create a DocumentDB cluster and start a MongoDB container |
+| `DescribeDBClusters` | List clusters and their connection details |
+| `DeleteDBCluster` | Stop and remove a cluster (must have no instances) |
+| `ModifyDBCluster` | Update engine version or IAM auth setting |
+| `CreateDBInstance` | Add an instance to a cluster |
+| `DescribeDBInstances` | List instances |
+| `DeleteDBInstance` | Remove an instance from a cluster |
+| `ModifyDBInstance` | Update instance class or IAM auth setting |
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FLOCI_SERVICES_DOCDB_ENABLED` | `true` | Enable or disable DocumentDB |
+| `FLOCI_SERVICES_DOCDB_MOCK` | `false` | Mock mode: skip the container and return a placeholder endpoint |
+| `FLOCI_SERVICES_DOCDB_DEFAULT_IMAGE` | `mongo:7.0` | MongoDB Docker image |
+| `FLOCI_SERVICES_DOCDB_DOCKER_NETWORK` | _(host default)_ | Docker network for container connectivity |
+
+Mock mode is useful for control-plane tests that do not need a live database; the cluster reports `localhost:27017` and no container is started.
+
+### Docker Compose
+
+DocumentDB needs the Docker socket so it can launch MongoDB containers. Each cluster's container is published on a dynamically assigned host port, returned by `DescribeDBClusters`.
+
+```yaml
+services:
+ floci:
+ image: floci/floci:latest
+ ports:
+ - "4566:4566"
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
+ environment:
+ FLOCI_SERVICES_DOCDB_DOCKER_NETWORK: my-project_default
+```
+
+For private registry authentication and other Docker settings see [Docker Configuration](../configuration/docker.md).
+
+## Examples
+
+### Management API (AWS CLI)
+
+```bash
+export AWS_ENDPOINT_URL=http://localhost:4566
+export AWS_DEFAULT_REGION=us-east-1
+export AWS_ACCESS_KEY_ID=test
+export AWS_SECRET_ACCESS_KEY=test
+
+# Create a DocumentDB cluster (starts a MongoDB container)
+aws docdb create-db-cluster \
+ --db-cluster-identifier my-docdb \
+ --engine docdb \
+ --master-username admin \
+ --master-user-password secret99
+
+# Get the cluster endpoint and port
+aws docdb describe-db-clusters \
+ --db-cluster-identifier my-docdb \
+ --query 'DBClusters[0].{Endpoint:Endpoint,Port:Port}'
+
+# Add an instance to the cluster
+aws docdb create-db-instance \
+ --db-instance-identifier my-docdb-instance \
+ --db-cluster-identifier my-docdb \
+ --db-instance-class db.r5.large \
+ --engine docdb
+
+# Delete instance and cluster
+aws docdb delete-db-instance \
+ --db-instance-identifier my-docdb-instance
+aws docdb delete-db-cluster \
+ --db-cluster-identifier my-docdb \
+ --skip-final-snapshot
+```
+
+### Data plane (Python + pymongo)
+
+```python
+from pymongo import MongoClient
+
+# Read the host and port from DescribeDBClusters — the port is dynamic
+# in real mode and is NOT guaranteed to be 27017.
+host, port = "localhost", 32768 # e.g. DBClusters[0].Endpoint / .Port
+client = MongoClient(f"mongodb://admin:secret99@{host}:{port}/")
+
+db = client["app"]
+db["people"].insert_one({"name": "Alice"})
+
+for doc in db["people"].find():
+ print(doc)
+
+client.close()
+```
+
+### Management API (Python / boto3)
+
+```python
+import boto3
+
+docdb = boto3.client(
+ "docdb",
+ endpoint_url="http://localhost:4566",
+ region_name="us-east-1",
+)
+
+cluster = docdb.create_db_cluster(
+ DBClusterIdentifier="my-docdb",
+ Engine="docdb",
+ MasterUsername="admin",
+ MasterUserPassword="secret99",
+)
+print(cluster["DBCluster"]["Endpoint"])
+```
+
+## Out of Scope
+
+- IAM database authentication for MongoDB connections (the flag is stored and echoed back, but connections are not SigV4-proxied).
+- TLS / `--tls` enforced connections.
+- Snapshot and restore operations.
+- Global clusters, replicas, and read-scaling beyond a single MongoDB container per cluster.
+- Parameter groups, subnet groups, and maintenance windows.
diff --git a/docs/services/index.md b/docs/services/index.md
index 6ff75b1bae..d1ba6ebe5a 100644
--- a/docs/services/index.md
+++ b/docs/services/index.md
@@ -39,6 +39,7 @@ Operation counts are exact. For dispatch-table services (Query and JSON 1.1) eac
| [Athena](athena.md) | `POST /` + `X-Amz-Target: AmazonAthena.*` | JSON 1.1 | 4 |
| [Glue](glue.md) | `POST /` + `X-Amz-Target: AWSGlue.*` | JSON 1.1 | 38 |
| [Neptune](neptune.md) | `POST /` with `Action=` param + Gremlin TCP proxy | Query + WebSocket | 8 |
+| [DocumentDB](docdb.md) | `POST /` with `Action=` param + MongoDB container | Query + MongoDB wire | 8 |
| [EMR](emr.md) | `POST /` + `X-Amz-Target: ElasticMapReduce.*` | JSON 1.1 | 24 |
| [Data Firehose](firehose.md) | `POST /` + `X-Amz-Target: Firehose_20150804.*` | JSON 1.1 | 6 |
| [ECS](ecs.md) | `POST /` + `X-Amz-Target: AmazonEC2ContainerServiceV20141113.*` | JSON 1.1 | 58 |
@@ -76,7 +77,7 @@ Operation counts are exact. For dispatch-table services (Query and JSON 1.1) eac
**Lambda, ElastiCache, RDS, MSK, ECS, EKS, and OpenSearch** spin up real Docker containers and support IAM authentication and SigV4 request signing, the same auth flow as production AWS. **RDS Data API** executes SQL against the local RDS containers through AWS-compatible REST JSON routes.
-**ECR** runs a shared `registry:2` container so the stock `docker` client can push and pull image bytes against repositories returned by the AWS-shaped control plane. **EKS** (real mode) starts a k3s container per cluster and exposes the Kubernetes API server on a host port. **OpenSearch** (real mode) starts an `opensearchproject/opensearch` container per domain and exposes the data-plane REST API on a host port.
+**ECR** runs a shared `registry:2` container so the stock `docker` client can push and pull image bytes against repositories returned by the AWS-shaped control plane. **EKS** (real mode) starts a k3s container per cluster and exposes the Kubernetes API server on a host port. **OpenSearch** (real mode) starts an `opensearchproject/opensearch` container per domain and exposes the data-plane REST API on a host port. **DocumentDB** starts a real `mongo` container per cluster and returns its host and port as the cluster endpoint, so any MongoDB driver can connect against the MongoDB-compatible wire protocol.
## Common Setup
diff --git a/mkdocs.yml b/mkdocs.yml
index d9ca31a18f..d98baf93e5 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -96,6 +96,7 @@ nav:
- MSK (Kafka): services/msk.md
- Glue: services/glue.md
- Neptune: services/neptune.md
+ - DocumentDB: services/docdb.md
- Athena: services/athena.md
- Data Firehose: services/firehose.md
- EventBridge: services/eventbridge.md