FerretDB: MongoDB Protocol

FerretDB provides a MongoDB-compatible protocol over PostgreSQL and the DocumentDB extension. Pigsty’s app/ferretdb runs only the stateless protocol proxy; PostgreSQL, the postgres database, the DocumentDB extensions, and the backend PostgreSQL login role must already exist. The mongo configuration template prepares these dependencies together.

Quick Start

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap
./configure -c mongo
./deploy.yml
./docker.yml -l pg-meta
./app.yml -l pg-meta

After installing mongosh or another MongoDB-compatible client separately, connect with the dedicated login declared by the template:

mongosh 'mongodb://mongod:[email protected]:27017/'

Key Configuration

Override template variables through apps.ferretdb.conf in the inventory. Do not edit the deployed /opt/ferretdb/.env directly:

app: ferretdb
apps:
  ferretdb:
    conf:
      FERRETDB_IMAGE: ghcr.io/ferretdb/ferretdb:2.7.0
      FERRETDB_POSTGRESQL_URL: 'postgres://mongod:[email protected]:5436/postgres?pool_min_conns=1&pool_max_conns=20'
      FERRETDB_BIND_ADDR: 127.0.0.1
      FERRETDB_PORT: 27017
      FERRETDB_AUTH: true
      FERRETDB_TELEMETRY: disabled

Port 5436 is Pigsty’s direct-to-current-primary PostgreSQL service. Linux host-gateway mapping lets the container connect through the local host while preserving Pigsty’s primary routing. The MongoDB port listens on loopback by default; change FERRETDB_BIND_ADDR explicitly only when remote clients require access.

FerretDB authenticates users through PostgreSQL, but it does not currently implement MongoDB authorization semantics, so MongoDB roles cannot provide access isolation. The template also does not enable MongoDB client TLS. Before exposing the service to an untrusted network, configure certificates and the FERRETDB_LISTEN_TLS* variables.

FerretDB releases specify a preferred DocumentDB version, while Pigsty may ship a newer compatible package. After upgrading either component, rerun an authenticated CRUD smoke test.

Optional Three-Node Topology

The mongo template includes a commented three-node PostgreSQL / DocumentDB cluster. Each node runs a FerretDB container, and HAProxy exposes standard port 27017 at the floating endpoint 10.10.10.4:27017 (mongo.pigsty). After enabling the complete pg-mongo cluster and the additional etcd members, run:

./configure -c mongo
./deploy.yml
./docker.yml -l pg-mongo
./app.yml -l pg-mongo
mongosh 'mongodb://mongod:[email protected]:27017/'

HAProxy uses TCP health checks to exclude stopped or unreachable FerretDB processes; the image’s built-in health check continues to verify the backend connection. Production deployments should also use a shared Silo or external S3-compatible pgBackRest repository so the same backup history remains available after a PostgreSQL primary failover.

References

• PostgreSQL Mongo configuration template
• Pigsty FerretDB template source
• FerretDB documentation