Skip to content

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 Docker containers behind an RDS-shaped control plane. As on AWS, the list form of DescribeDBClusters / DescribeDBInstances — on the docdb endpoint and the rds endpoint alike — returns DocumentDB, Neptune and RDS records together; the engine filter (docdb, neptune, aurora-postgresql, ...) narrows it. 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
DescribeDBClusterSnapshots Return an empty cluster-snapshot list (snapshots are not modeled)
DescribeGlobalClusters List global clusters — always empty, as none are modeled
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
ListTagsForResource List a cluster's or instance's tags
AddTagsToResource Add or overwrite tags on a cluster or instance
RemoveTagsFromResource Remove tags by key from a cluster or instance

CreateDBCluster stores DBSubnetGroupName, DBClusterParameterGroupName, VpcSecurityGroupIds, StorageEncrypted, KmsKeyId (resolved to the key ARN), BackupRetentionPeriod, both windows, Port, DeletionProtection and Tags, and DescribeDBClusters returns them; ModifyDBCluster changes the ones AWS lets change. References are checked as on AWS (the subnet group and cluster parameter group are the RDS records, security groups are EC2's, the key must exist and be enabled), and so are the windows (30-minute minimum, no overlap). Omitted values take the AWS defaults — default, default.docdb<family>, the VPC's default security group, one day of backups — with deterministic windows 04:00-06:00 / mon:00:00-mon:03:00 where AWS picks random ones. CreateDBInstance keeps AutoMinorVersionUpgrade, PreferredMaintenanceWindow, CopyTagsToSnapshot, PromotionTier and Tags. EngineVersion must be one a live account lists (3.6.0, 4.0.0, 5.0.0, 5.0.1, 8.0.0, 8.0.1, or the major.minor form of one); any other is refused with Cannot find version X for docdb, on create and on modify.

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.

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.

Examples

Management API (AWS CLI)

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)

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)

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.