DocumentDB is included in the pglayers-azure profile image, which mirrors the open-source extensions available in Azure Database for PostgreSQL. This post walks through running the image and talking to it from a MongoDB client end to end -- including a password gotcha that trips people up.

1. Start the container

Run the pglayers-azure image, exposing PostgreSQL on 5432 and the DocumentDB gateway on 10260 (the port the wire protocol listens on):

docker run -d --name pglayers-docdb \
  -e POSTGRES_PASSWORD=secret \
  -p 5432:5432 -p 10260:10260 \
  ghcr.io/pglayers/pglayers-azure:18

The profile image auto-configures everything at boot: it sets shared_preload_libraries (including pg_documentdb_gw_host, the gateway worker), appends the required GUCs, and auto-creates the documentdb extension on first init. Within a second or two the log shows TCP listener(s) bound to port 10260 and the gateway is ready. You don't need to run CREATE EXTENSION yourself.

Use PG 18 (isolated layout) or PG 17. DocumentDB is built only for 17 and 18 -- not 19 -- so don't use pglayers-azure:19 for this.

2. Create a MongoDB user

The gateway uses native SCRAM authentication, and its configuration blocks a set of role name prefixes (documentdb, citus, pg, internal_role). That means you can't reuse the postgres superuser -- you need a fresh role with a password.

The intuitive approach is DocumentDB's own documentdb_api.create_user() function, but on a stock image it fails:

ERROR:  password type is not a plain text
CONTEXT:  ... CREATE ROLE mongoadmin WITH LOGIN PASSWORD 'SCRAM-SHA-256$...'

The reason: the server runs with password_encryption = scram-sha-256, so create_user() pre-hashes the password, but DocumentDB installs a check_password hook that wants the plaintext value (it builds the SCRAM verifier itself). The two disagree and the call is rejected.

The path that works is a direct CREATE ROLE with a plaintext password, granting DocumentDB's built-in roles. The hook then computes the verifier the gateway expects:

docker exec pglayers-docdb psql -U postgres -c \
  "CREATE ROLE mongoadmin WITH LOGIN INHERIT PASSWORD 'Secret_123' \
   IN ROLE documentdb_admin_role, documentdb_readonly_role;"

Upstream's standalone documentdb-local image sidesteps this by taking --username/--password at container start and bootstrapping the first user itself. In pglayers the gateway runs as a PostgreSQL background worker, so you create the user via SQL as above.

3. Connect from a MongoDB client

The gateway serves TLS with an auto-generated self-signed certificate, so clients connect with TLS enabled and certificate validation relaxed. The connection string is:

mongodb://mongoadmin:Secret_123@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true&authMechanism=SCRAM-SHA-256

Here's a full round-trip with mongosh (run from a throwaway container on the host network) -- insert, filtered find, and an aggregation:

docker run --rm --network host mongodb/mongodb-community-server:latest mongosh --quiet \
  "mongodb://mongoadmin:Secret_123@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true&authMechanism=SCRAM-SHA-256" \
  --eval 'const db = db.getSiblingDB("shop");
          db.products.insertMany([{name:"Widget",price:9.99},{name:"Gadget",price:19.5}]);
          printjson(db.products.find({price:{$gte:10}}).toArray());
          printjson(db.products.aggregate([{$group:{_id:null,avg:{$avg:"$price"}}}]).toArray());'

This inserts two documents, returns Gadget for the $gte filter, and computes an average price of 14.745. The exact same URI works from pymongo or the Node.js driver:

from pymongo import MongoClient

client = MongoClient(
    "mongodb://mongoadmin:Secret_123@localhost:10260/"
    "?tls=true&tlsAllowInvalidCertificates=true&authMechanism=SCRAM-SHA-256"
)
db = client["shop"]
db.products.insert_one({"name": "Sprocket", "price": 4.5})
print(db.products.find_one({"name": "Sprocket"}))

Because it's all PostgreSQL underneath, the same data is queryable from SQL -- for example via documentdb_api.count_query('shop', ...) -- so you can mix document workloads and relational queries against one database.

Production notes

• TLS. tlsAllowInvalidCertificates=true is only appropriate for the bundled self-signed certificate. For production, mount your own certificate and a custom /etc/documentdb/gateway_config.json to set the port, TLS mode, and blocked role prefixes.
• PostgreSQL version. Stick to PG 17 or 18; DocumentDB isn't built for 19 yet.
• Auto-created extensions. The gateway needs the documentdb extension to exist, which the profile image creates for you on first init. To opt out, set PGLAYERS_CREATE_EXTENSIONS=none.

Try it

Everything above is a single docker run plus one CREATE ROLE away. See the pglayers repository for the full extension list and profile documentation, and the DocumentDB project for the supported MongoDB API surface.

pglayers fixes this. It gives you 50+ pre-built PostgreSQL extensions as stackable Docker image layers. You add one line per extension to your Dockerfile -- no compilation, no package managers, no build tools.

The problem

Suppose you want PostgreSQL with pgvector and pg_cron. Today your options are:

1. Build from source. Install build-essential, postgresql-server-dev-17, clone the repos, run make install. Repeat every time you upgrade. Slow, fragile, and bloats your image with compilers you don't need at runtime.
2. Use a third-party image. Someone else built an image with a particular set of extensions. Maybe it includes what you need, maybe it doesn't. You lose control over the base image, update schedule, and security patches.
3. PGDG packages. Install from apt.postgresql.org. Works, but the package manager pulls transitive dependencies, and you're mixing package management with Docker layer caching in ways that complicate reproducibility.

None of these compose well. If you need pgvector and PostGIS and TimescaleDB and pg_cron, each approach compounds its complexity.

How pglayers works

Each extension is published as a minimal Docker image (built FROM scratch) containing only the extension's compiled binaries: the .so shared library, the .control file, and the SQL migration scripts. These files are laid out at exactly the paths PostgreSQL expects:

/usr/lib/postgresql/17/lib/vector.so
/usr/share/postgresql/17/extension/vector.control
/usr/share/postgresql/17/extension/vector--0.8.3.sql

To use them, you write a standard multi-stage COPY --from in your Dockerfile:

FROM postgres:17

COPY --from=ghcr.io/pglayers/pgx-pgvector:17  / /
COPY --from=ghcr.io/pglayers/pgx-pg_cron:17   / /
COPY --from=ghcr.io/pglayers/pgx-postgis:17   / /

That's it. Docker pulls the pre-built layers from the registry and overlays them onto the official image. No compilation happens at build time -- it's just file copies. The result is a single image with exactly the extensions you chose.

Then you can CREATE EXTENSION as usual:

CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pg_cron;
CREATE EXTENSION IF NOT EXISTS postgis;

Ready-to-use profile images

If you don't want to pick individual extensions, pglayers provides pre-built combined images called profiles:

# All 50+ extensions, pre-configured
docker run -d -e POSTGRES_PASSWORD=secret ghcr.io/pglayers/pglayers-full:17

# Extensions matching Azure Database for PostgreSQL
docker run -d -e POSTGRES_PASSWORD=secret ghcr.io/pglayers/pglayers-azure:17

Profile images come with shared_preload_libraries already configured, companion processes started (like pg_lake's DuckDB backend), and all the GUC settings extensions need. Just docker run and you have a fully-loaded PostgreSQL instance.

The azure profile also includes DocumentDB, which provides MongoDB wire protocol compatibility on port 10260. MongoDB clients (mongosh, pymongo, the Node.js driver) connect directly -- same engine as Azure DocumentDB.

What's included

pglayers ships 53 extensions across PostgreSQL 17, 18, and 19. A few highlights:

• pgvector + pgvectorscale -- vector similarity search for AI/ML embeddings, with high-performance DiskANN indexing
• PostGIS + pgRouting -- the full geospatial stack (geometry, geography, raster, routing)
• TimescaleDB -- hypertables, compression, and continuous aggregates for time-series data
• pg_cron -- cron-like job scheduler running inside the database
• DocumentDB -- MongoDB-compatible document engine with wire protocol support
• pg_lake -- query Iceberg tables and data lake files (Parquet, CSV, JSON) directly from PostgreSQL
• pg_duckdb -- DuckDB's columnar analytics engine embedded in Postgres for OLAP workloads
• Apache AGE -- graph database with openCypher query support

All images are multi-architecture (linux/amd64 and linux/arm64), so Docker automatically pulls the right binary for your platform -- whether you're on an M-series Mac or an x86 CI runner.

Quality guarantees

Every extension goes through a CI pipeline that checks:

• No file collisions -- extension pairs are compared to ensure they don't overwrite each other's files
• No base image overwrites -- extensions never replace files from the official postgres image
• Shared library resolution -- ldd verifies all transitive dependencies are present
• CREATE EXTENSION -- every extension loads successfully
• Functional smoke tests -- each extension is exercised with real queries, not just loaded

Getting started

The fastest way to try pglayers is the full profile image:

docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=secret \
  ghcr.io/pglayers/pglayers-full:17

Then connect and enable any extension:

psql -h localhost -U postgres
CREATE EXTENSION vector;
CREATE EXTENSION postgis;
SELECT '[1,2,3]'::vector <-> '[4,5,6]'::vector AS distance;

To build a custom image with only the extensions you need, create a Dockerfile:

FROM postgres:17

COPY --from=ghcr.io/pglayers/pgx-pgvector:17       / /
COPY --from=ghcr.io/pglayers/pgx-timescaledb:17    / /
COPY --from=ghcr.io/pglayers/pgx-pg_cron:17        / /

RUN echo "shared_preload_libraries = 'timescaledb,pg_cron'" \
    >> /usr/share/postgresql/postgresql.conf.sample

Build and run:

docker build -t my-postgres .
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=secret my-postgres

Open source

pglayers is MIT licensed and hosted on GitHub. The project welcomes contributions -- whether that's adding a new extension, improving tests, or reporting issues.

github.com/pglayers/pglayers

pglayers stands on the shoulders of the PostgreSQL community: the PostgreSQL Global Development Group, the PGDG APT repository maintainers, the official Docker image maintainers, and every extension author who releases their work under permissive open-source licenses.