FerretDB on AWS User Guide

Overview

This image runs FerretDB, the truly open source document database that is compatible with the MongoDB wire protocol. FerretDB lets you keep using MongoDB drivers, the mongosh shell and the MongoDB query and aggregation language, while your data is stored in PostgreSQL through the DocumentDB extension. The image is delivered as a ready-to-use database appliance: postgresql.service and ferretdb.service are enabled and start on boot, so the moment an engineer connects over SSH the MongoDB-compatible endpoint is already answering.

This is a headless database service. There is no web interface. FerretDB speaks the MongoDB wire protocol on the loopback interface (127.0.0.1:27017) and exposes its debug and metrics HTTP handlers on loopback (127.0.0.1:8088), so neither is exposed to the network by the shipped security group, which opens port 22 only. A strong, unique database password is generated automatically on the first boot of every instance and written to a root-only credentials file, so no shared secret is ever baked into the image. Clients authenticate against PostgreSQL using SCRAM-SHA-256.

The PostgreSQL data directory is relocated onto a dedicated, independently resizable EBS data volume mounted at /var/lib/ferretdb, so the database grows on durable storage you can expand without touching the boot volume. The DocumentDB extension is already created in the backend database, ready for your first collection.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for FerretDB. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.medium or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a short time after the instance state becomes Running and the status checks pass: the image generates the per-instance database password, creates the PostgreSQL role and starts FerretDB against it.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg FerretDB Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 from your management network.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.medium \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=ferretdb}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem admin@<public-ip>

A welcome banner prints the most useful commands. The per-instance database password and the ready-to-paste connection string live in a root-only credentials file:

sudo cat /root/ferretdb-credentials.txt

This file contains the generated ferretdb.password, the mongosh connection string, and notes on the services, the debug endpoint and the data directory. The password is unique to this instance and is created on first boot, so nothing is shared across deployments.

Step 4: Verify the Services

FerretDB and its PostgreSQL backend run as system services that are enabled and started on boot. Confirm both are active:

systemctl is-active postgresql ferretdb

Each line prints active. For the full unit status of FerretDB, including the main PID and memory use, run:

systemctl status ferretdb --no-pager

Confirm the installed binary and version, which is FerretDB 2.7.0 on this image:

ferretdb --version

You should see version 2.7.0 reported. The ferretdb binary is installed at /usr/bin/ferretdb and is on the system path.

Step 5: Connect with the MongoDB Shell

FerretDB speaks the MongoDB wire protocol on the loopback interface (127.0.0.1:27017). The image ships the MongoDB shell, mongosh. Read the generated password into a shell variable, then connect:

PASS=$(sudo grep '^ferretdb.password=' /root/ferretdb-credentials.txt | cut -d= -f2-)
mongosh "mongodb://ferretdb:${PASS}@127.0.0.1:27017/" --quiet --eval 'db.runCommand({ping:1})'

You should see { ok: 1 }, confirming the MongoDB-compatible endpoint is answering and your credentials authenticated against PostgreSQL. Insert a document into a collection and read it back, exactly as you would with MongoDB:

PASS=$(sudo grep '^ferretdb.password=' /root/ferretdb-credentials.txt | cut -d= -f2-)
mongosh "mongodb://ferretdb:${PASS}@127.0.0.1:27017/" --quiet --eval '
  var d = db.getSiblingDB("appdb");
  d.products.insertOne({ name: "widget", price: 9.99, tags: ["new", "sale"] });
  printjson(d.products.find().toArray());
'

The document round-trips through FerretDB into PostgreSQL and is returned by the find. You can use collections, indexes, the aggregation pipeline and the rest of the MongoDB query language; every operation is translated to SQL and persisted in the backend.

Step 6: The Debug and Metrics Endpoint

FerretDB exposes a debug HTTP handler on loopback (127.0.0.1:8088). The liveness probe returns HTTP 200 when FerretDB is ready to accept connections:

curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8088/debug/livez

That prints 200. The readiness probe additionally confirms a backend PostgreSQL connection can be established:

curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8088/debug/readyz

Prometheus-format metrics are served at /debug/metrics for scraping:

curl -fsS http://127.0.0.1:8088/debug/metrics | grep -E '^ferretdb_|^go_goroutines'

Step 7: The PostgreSQL Backend and Data Volume

FerretDB stores all data in PostgreSQL 17 through the DocumentDB extension. The PostgreSQL data directory lives on a dedicated EBS volume mounted at /var/lib/ferretdb, keeping the database off the operating system disk so you can resize or snapshot it independently. Confirm the mount:

df -h /var/lib/ferretdb

The DocumentDB extension is already created in the backend postgres database. You can confirm it directly:

sudo -u postgres psql -tAc "SELECT extname FROM pg_extension WHERE extname='documentdb';"

That prints documentdb. To grow the volume, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device.

Step 8: Serving Remote Clients

By default FerretDB binds the MongoDB-compatible endpoint to loopback only, and the security group opens port 22 alone, so the database is private to the instance. To serve remote clients, bind FerretDB to an external address by overriding the listen address (set FERRETDB_LISTEN_ADDR=0.0.0.0:27017 with sudo systemctl edit ferretdb, then sudo systemctl restart ferretdb), open port 27017 in the instance security group to your trusted CIDR only, and front the endpoint with TLS. Point your application's MongoDB connection string at the instance using the same ferretdb user and generated password.

Support

This image is published and supported by cloudimg. Support covers connection strings and drivers, authentication and roles, indexes and the aggregation pipeline, the PostgreSQL backend and the DocumentDB extension, backups, capacity planning and upgrade planning. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.