FerretDB on VPS: Harnessing PostgreSQL Power with Native MongoDB Syntax

Introduction: The Database Dilemma in Modern Architecture

In the landscape of modern software development, choosing the right database architecture is a critical decision that influences scalability, maintenance, and licensing costs. For years, document databases like MongoDB have been favored for their flexibility, dynamic schemas, and intuitive JSON-like document model. However, changes in MongoDB's licensing (specifically the transition to the Server Side Public License or SSPL) have created compliance and financial hurdles for enterprise environments.

On the other side of the spectrum lies PostgreSQL, the gold standard of open-source relational databases, renowned for its rock-solid reliability, ACID compliance, and robust ecosystem. What if you could combine the seamless developer experience of MongoDB's syntax and drivers with the enterprise-grade stability of a PostgreSQL backend? This is precisely where FerretDB comes into play. In this comprehensive guide, we will explore how to deploy FerretDB on a Virtual Private Server (VPS) to achieve the ultimate hybrid data solution.

What is FerretDB and Why Should You Care?

FerretDB is an open-source proxy that translates MongoDB wire protocol queries into SQL, executing them against a PostgreSQL database backend. It acts as a stateless translation layer, meaning your applications can continue using standard MongoDB drivers, ODM frameworks (like Mongoose or Prisma), and management tools (like MongoDB Compass) without realizing that the data actually resides in PostgreSQL tables.

Key Benefits of the FerretDB + PostgreSQL Architecture

True Open-Source Compliance: Avoid the complexities of the SSPL license. PostgreSQL and FerretDB operate under permissive open-source licenses, ensuring your infrastructure remains compliant and cost-effective.
Unified Infrastructure: If your organization already relies on PostgreSQL for relational data, adding FerretDB allows you to support document-store workloads without introducing a separate, complex database cluster to manage.
SQL Power on NoSQL Data: Because the data is stored in PostgreSQL (often leveraging JSONB types), advanced data analysts can run complex SQL queries, joins, and reporting tools directly over your document data.
Driver Compatibility: Developers do not need to learn a new language or migrate codebases. Your existing MongoDB queries work out of the box.

Prerequisites for VPS Deployment

Before initiating the deployment, ensure your environment meets the following baseline requirements:

A VPS running a clean installation of a modern Linux distribution (such as Ubuntu 24.04 LTS or Debian 12).
A minimum of 2GB RAM and 2 vCPUs (recommended for small to medium workloads).
A non-root user account with sudo privileges.
Docker and Docker Compose installed on the system (the most efficient way to manage FerretDB and PostgreSQL side-by-side).
A domain name pointing to your VPS IP address (optional, but highly recommended if securing the endpoint with TLS).

Step-by-Step Guide to Deploying FerretDB via Docker Compose

Using Docker Compose simplifies the orchestration of the FerretDB proxy and the underlying PostgreSQL database, ensuring isolated environments and easy configuration management.

Step 1: Setting Up the Project Directory

Log into your VPS via SSH and create a dedicated directory for your deployment stack:

mkdir ~/ferretdb-stack
cd ~/ferretdb-stack

Step 2: Designing the Configuration File

Create a file named docker-compose.yml using your preferred text editor (such as nano or vim). Paste the following highly optimized configuration:

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: postgres_backend
    environment:
      POSTGRES_USER: ferret_admin
      POSTGRES_PASSWORD: SecurePassword2026!
      POSTGRES_DB: ferretdb_store
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "127.0.0.1:5432:5432"
    networks:
      - database_net
    restart: always

  ferretdb:
    image: ghcr.io/ferretdb/ferretdb:latest
    container_name: ferretdb_proxy
    environment:
      - FERRETDB_POSTGRESQL_URL=postgres://ferret_admin:SecurePassword2026!@postgres:5432/ferretdb_store
      - FERRETDB_LISTEN_ADDR=0.0.0.0:27017
    ports:
      - "27017:27017"
    depends_on:
      - postgres
    networks:
      - database_net
    restart: always

volumes:
  pgdata:

networks:
  database_net:
    driver: bridge

Security Warning: Always replace SecurePassword2026! with a strong, randomly generated cryptographic password before launching production services. Notice that the PostgreSQL port is bound to localhost to prevent external unauthorized exposure.

Step 3: Launching the Services

Execute the docker command to download the images and run the containers in detached mode:

docker compose up -d

Verify that both containers are active and running flawlessly by reviewing the status logs:

docker compose ps
docker compose logs ferretdb

Connecting to FerretDB: Validation and Integration

With FerretDB listening actively on port 27017, it mimics a traditional MongoDB instance. Let us validate the connection using standard tools.

Connecting via MongoDB Shell (mongosh)

If you have the MongoDB shell installed on your local machine, run the connection string pointing to your VPS public IP address:

mongosh "mongodb://your_vps_public_ip:27017/"

Once connected, you can interact with it precisely as you would with MongoDB. Run the following database commands to test document insertion and retrieval:

use corporate_analytics

db.customers.insertOne({
  name: "Acme Corporation",
  industry: "Technology",
  active: true,
  metadata: { created_at: new Date() }
})

db.customers.find({ industry: "Technology" })

FerretDB intercepts these operations, dynamically generates standard PostgreSQL SQL queries, translates document schemas into PostgreSQL's optimized JSONB format, and commits the records securely to disk.

Production Considerations and Best Practices

While deploying FerretDB on a VPS is incredibly straightforward, running it in an enterprise production environment demands adherence to rigorous structural and operational standards.

1. Network Security and Firewalls

Never leave port 27017 exposed broadly to the open internet without robust firewall rules or authentication layers. Use your cloud provider's firewall or local ufw (Uncomplicated Firewall) configurations to restrict incoming traffic explicitly to your application servers' IP addresses:

sudo ufw allow from your_app_server_ip to any port 27017

2. Backup and Recovery Strategy

Since the core state and data live completely inside PostgreSQL, you do not use traditional mongodump utilities. Instead, establish robust, automated backup pipelines using pg_dump or enterprise tools like pgBackRest. This ensures high-fidelity point-in-time recoveries.

3. Query Performance and Indexing

FerretDB translates MongoDB indexes into corresponding PostgreSQL indexes. However, it is paramount to monitor performance closely via query analyzers. Ensure your heavily filtered document fields are supported by appropriate backing indices to prevent performance degradation as datasets scale into millions of records.

Conclusion

FerretDB breaks down the artificial barriers between relational and non-relational database models. By combining the legendary architectural reliability of PostgreSQL with the agile, flexible interface of MongoDB, developers get the best of both worlds without licensing complications or architectural bloat. Deploying FerretDB on a VPS provides a highly isolated, highly cost-effective, and deeply performant database proxy layer designed to fuel next-generation enterprise applications.