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.mdindex 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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 Setupdiff --git a/mkdocs.yml b/mkdocs.ymlindex 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