DPTCloud
Back to articles
Technology Insight

FerretDB Deployment Guide: How to Run MongoDB Workloads on PostgreSQL Backend

May 30, 2026

Introduction: The Database Licensing Dilemma and the Rise of FerretDB

In recent years, the open-source community has faced a significant shift. When MongoDB transitioned from the GNU Affero General Public License (AGPL) to the Server Side Public License (SSPL), many enterprises and developers found themselves in a difficult compliance dilemma. The new license terms made it challenging for cloud providers and managed service platforms to offer MongoDB without open-sourcing their own infrastructure code, sparking a search for true open-source alternatives.

Enter FerretDB. Formerly known as MangoDB, FerretDB is an open-source proxy that translates MongoDB wire protocol queries into SQL, executing them against a PostgreSQL backend. This architectural breakthrough means you can keep using all your existing MongoDB drivers, queries, and tools (like Compass or Mongoose), while your actual data resides safely within the highly reliable, ACID-compliant ecosystem of PostgreSQL.

For businesses utilizing a Virtual Private Server (VPS), configuring FerretDB offers the ultimate sweet spot: the document-oriented flexibility of MongoDB for application development, combined with the proven operational stability and relational robustness of PostgreSQL. In this comprehensive guide, we will walk through the exact steps required to provision, configure, and secure FerretDB on a standard Linux VPS.

Key Takeaway: FerretDB allows you to achieve absolute open-source freedom. Your application thinks it is talking to MongoDB, but your infrastructure benefits from the mature data integrity of PostgreSQL.
---

Understanding the Architecture: How FerretDB Bridges the Gap

Before diving into the command-line setup, it is crucial to understand how FerretDB handles data traffic. FerretDB does not store data itself; it acts as a stateless translation layer.

  • The Client/Application Layer: Your application uses standard MongoDB drivers (Node.js, Python, Go, etc.) and connects via the standard MongoDB connection string format (mongodb://...).
  • The Proxy Layer (FerretDB): FerretDB listens on the standard MongoDB port (usually 27017). It intercepts the BSON encoded queries, parses them, and dynamically converts them into equivalent SQL queries.
  • The Storage Layer (PostgreSQL): PostgreSQL receives the SQL queries, utilizes its native JSONB capabilities to handle the unstructured document data, and returns the results back up the chain.

Because PostgreSQL has heavily optimized its JSONB data type over the past decade, the performance penalty of this translation layer is surprisingly minimal for most standard transactional workloads.

---

Prerequisites and Environment Setup

To follow this tutorial seamlessly, ensure your environment meets the following baseline requirements:

  1. A clean VPS running Ubuntu 24.04 LTS or 22.04 LTS with root or sudo privileges.
  2. At least 2GB of RAM (PostgreSQL and FerretDB can run on lower resources, but 2GB ensures stable production buffers).
  3. A configured firewall (such as UFW) to protect database ports from public exposure.
  4. Docker and Docker Compose installed (highly recommended for rapid deployment and isolated dependency management).
---

Step-by-Step Guide: Deploying FerretDB on a VPS

While you can install FerretDB from native packages, utilizing Docker Compose is the industry-standard best practice for managing containerized database layers. It simplifies networking and allows you to spin up both PostgreSQL and FerretDB simultaneously.

Step 1: Preparing the Configuration Directory

Connect to your VPS via SSH and create a dedicated project directory to store your environment variables and orchestration files:

mkdir -p /opt/ferretdb-stack
cd /opt/ferretdb-stack

Step 2: Crafting the Docker Compose Configuration

Create a docker-compose.yml file using your preferred text editor (such as Nano or Vim). This file will define two services: the PostgreSQL backend and the FerretDB proxy layer.

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: ferretdb-postgres
    environment:
      POSTGRES_USER: ferret_admin
      POSTGRES_PASSWORD: SecurePgPassword2026
      POSTGRES_DB: ferretdb_backend
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "127.0.0.1:5432:5432"
    restart: always

  ferretdb:
    image: ghcr.io/ferretdb/ferretdb:latest
    container_name: ferretdb-proxy
    environment:
      FERRETDB_POSTGRESQL_URL: "postgres://ferret_admin:SecurePgPassword2026@postgres:5432/ferretdb_backend?sslmode=disable"
      FERRETDB_LISTEN_ADDR: "0.0.0.0:27017"
    ports:
      - "27017:27017"
    depends_on:
      - postgres
    restart: always

volumes:
  pgdata:

Let's dissect the critical configurations within this file:

  • PostgreSQL Port Binding: We bound PostgreSQL to 127.0.0.1:5432 to ensure the database engine is only accessible internally within the VPS, significantly reducing the security attack surface.
  • FERRETDB_POSTGRESQL_URL: This environment variable tells FerretDB exactly how to authenticate against our PostgreSQL container inside the internal Docker network.
  • FERRETDB_LISTEN_ADDR: Setting this to 0.0.0.0:27017 allows FerretDB to accept external connection requests on the standard MongoDB port, allowing external applications to connect.

Step 3: Launching the Stack

Execute the following command to download the images and launch the containers in detached (background) mode:

docker compose up -d

Verify that both containers are running successfully by checking their operational status:

docker compose ps
---

Testing and Verifying the Connection

Now that your FerretDB instance is up and running on your VPS, it is time to verify that it correctly intercepts and responds to MongoDB commands. You can test this from a remote machine using the native mongosh (MongoDB Shell) CLI client.

Run the following command on your local terminal, replacing your_vps_ip with the actual public IP address of your virtual private server:

mongosh "mongodb://your_vps_ip:27017/test_db"

Once connected, you will be greeted by the standard MongoDB shell prompt. Let us run a series of routine operations to confirm full operational compatibility:

// 1. Insert a document
db.users.insertOne({ name: "John Doe", email: "[email protected]", role: "Admin" })

// 2. Query the document using standard filters
db.users.find({ role: "Admin" })

// 3. Verify collection statistics
db.users.stats()

If these operations execute successfully without throwing syntax errors, your setup is operating correctly. Behind the scenes, FerretDB converted your JavaScript-like BSON command into a PostgreSQL JSONB query, wrote it to a table in the ferretdb_backend database, and sent back a response perfectly formatted as a MongoDB cursor object.

---

Production Considerations: Security and Performance

While running FerretDB via Docker is straightforward, deploying it into a live enterprise or production environment requires rigorous adherence to security and database management best practices.

1. Enforcing Authentication

By default, the basic configuration allows unauthenticated access if port 27017 is exposed. Ensure you configure MongoDB-style authentication within FerretDB by reviewing their official documentation regarding authentication proxy headers and user management to lock down your collections.

2. Implementing Firewall Controls (UFW)

Never leave your database port wide open to the public internet unless absolutely necessary. If your application server lives on a separate VPS, restrict port 27017 access exclusively to that specific IP address:

sudo ufw allow from [Your_App_Server_IP] to any port 27017

3. Memory and Vacuuming in PostgreSQL

Because FerretDB heavily utilizes PostgreSQL's JSONB features, database tables will experience frequent updates and deletes depending on your application profile. Ensure that your PostgreSQL instance has an optimized Autovacuum schedule configured to prevent table bloat and preserve high read/write speeds over time.

---

Conclusion: True Open-Source Freedom

FerretDB represents a vital shift back toward uncompromised open-source infrastructure. By decoupling the MongoDB interface from its underlying proprietary engine, your business can bypass licensing restrictions, control cloud costs, and leverage the legendary reliability of a PostgreSQL database backend.

Whether you are looking to scale back high licensing costs or simply want to centralize your operations around PostgreSQL while retaining flexible document-store syntax, configuring FerretDB on a VPS provides an elegant, scalable, and highly performant alternative for modern software architectures.

FerretDB Deployment Guide: How to Run MongoDB Workloads on PostgreSQL Backend | DPTCloud