Deploying FerretDB on a VPS: Leveraging PostgreSQL with Native MongoDB Syntax

Introduction: The Open-Source Database Dilemma

In the modern enterprise software landscape, engineering teams frequently face a challenging architectural crossroad. On one hand, MongoDB offers an unparalleled document-oriented developer experience, allowing for rapid schema prototyping and intuitive JSON-like queries. On the other hand, MongoDB's transition to the Server Side Public License (SSPL) has introduced significant compliance risks and financial overhead for businesses operating in cloud environments. Meanwhile, PostgreSQL remains the gold standard for relational data consistency, open-source compliance, and enterprise-grade reliability.

What if you could combine the seamless developer experience of MongoDB with the trusted, open-source foundation of PostgreSQL? Enter FerretDB. FerretDB acts as an open-source proxy that translates MongoDB wire protocol queries into PostgreSQL-compatible SQL on the fly. This blog post provides a comprehensive, technical blueprint for deploying FerretDB on a Virtual Private Server (VPS), enabling your organization to leverage PostgreSQL as a backend while communicating entirely via native MongoDB syntax.

---

Why Choose FerretDB over Standard MongoDB?

Before diving into the technical deployment, it is critical to understand the strategic business and technical advantages of this architecture:

Licensing Peace of Mind: FerretDB is licensed under the Apache 2.0 license, entirely eliminating the legal ambiguities and vendor lock-in associated with MongoDB's SSPL.
Infrastructure Consolidation: If your enterprise already relies heavily on PostgreSQL for relational workloads, FerretDB allows you to run document-database workloads on the exact same database engine, drastically reducing operational complexity and DBA overhead.
Zero Code Rewrite: Because FerretDB speaks the MongoDB wire protocol, your existing application code, ODM frameworks (like Mongoose or Prisma), and database tools (like Compass) work out of the box.
PostgreSQL Robustness: Benefit from PostgreSQL's advanced features, including mature ACID compliance, robust point-in-time recovery (PITR), and extensive ecosystem extensions.

---

Architecture Overview

When deploying this solution on a VPS, the architectural flow operates as a classic three-tier system wrapped into localized network spaces. Your application directs its standard MongoDB connection string to the FerretDB service. FerretDB intercepts these BSON-encoded commands, parses them, translates them into optimized SQL queries, and executes them against a target PostgreSQL database instance.

Key Architectural Insight: FerretDB does not store data itself. It is a stateless translation layer. All persistence, indexing, and data durability guarantees are inherited directly from your backend PostgreSQL engine.

---

Prerequisites for VPS Deployment

To successfully execute this guide, ensure your Virtual Private Server meets the following minimum requirements:

Operating System: Ubuntu 22.04 LTS or Ubuntu 24.04 LTS recommended.
Hardware Specs: Minimum 2 vCPUs, 2GB RAM, and SSD storage (scale based on your expected concurrent connections and dataset size).
Software Dependency: Docker and Docker Compose installed on the host system to simplify container orchestration.
Network: A public static IP address with port 27017 (MongoDB standard port) secured behind a firewall.

---

Step-by-Step Deployment Guide via Docker Compose

Using Docker Compose is the most reliable, isolated, and scalable method to provision both FerretDB and PostgreSQL simultaneously on a single VPS host. Follow these technical steps to initiate your stack.

Step 1: Project Setup and Directory Structure

Log into your VPS via SSH and create a dedicated workspace directory for your database infrastructure:

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

Step 2: Configuring the Docker Compose Manifest

Create a docker-compose.yml file within your directory. This file defines the PostgreSQL container, its persistent storage volumes, and the FerretDB service mapped to the standard MongoDB port 27017.

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    container_name: ferretdb-postgres
    environment:
      POSTGRES_USER: ferret_admin
      POSTGRES_PASSWORD: SuperSecurePassword123!
      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:SuperSecurePassword123!@postgres:5432/ferretdb_backend?sslmode=disable"
      FERRETDB_LISTEN_ADDR: "0.0.0.0:27017"
    ports:
      - "27017:27017"
    depends_on:
      - postgres
    restart: always

volumes:
  pgdata:
    driver: local

Step 3: Launching the Services

Execute the Docker Compose command in detached mode to pull the necessary official images and spin up your database translation stack:

docker compose up -d

Verify that both containers are up and running perfectly by checking the process logs:

docker compose ps
docker compose logs ferretdb

---

Verifying the Connection Using MongoDB Tools

Once your containers are fully operational, your VPS is officially listening for incoming MongoDB traffic. You can verify this using the standard MongoDB Shell (mongosh) or graphical user interfaces like MongoDB Compass.

To connect from your local terminal or application server, utilize the standard MongoDB URI format:

mongodb://ferret_admin:SuperSecurePassword123!@your_vps_public_ip:27017/ferretdb_backend?authSource=admin

Inside the MongoDB Shell, you can execute standard CRUD actions seamlessly. For instance:

use company_db;
db.employees.insertOne({ name: "Alice", role: "Lead Engineer", active: true });
db.employees.find({ active: true });

Behind the scenes, FerretDB converts these exact document manipulations into dynamic PostgreSQL tables, schemas, and structural JSONB inputs.

---

Production Optimization and Security Hardening

Running database infrastructure on a public VPS requires meticulous security considerations. Ensure you implement the following policies before routing live production traffic to your FerretDB deployment:

1. Network Isolation and Firewalls

Never expose port 27017 unconditionally to the entire public internet. Use native Linux firewalls (such as UFW) to whitelist only the specific IP addresses of your application servers or microservices:

sudo ufw allow from your_app_server_ip to any port 27017 proto tcp

2. Implement TLS Encryption

In production environments, transmitting raw data over unencrypted channels introduces severe vulnerabilities. Configure FerretDB with TLS certificates (e.g., via Let's Encrypt or your internal CA) by mapping the certificates into your Docker container and applying the FERRETDB_TLS_CERT_FILE and FERRETDB_TLS_KEY_FILE environment variables.

3. PostgreSQL Performance Tuning

Because performance relies directly on the underlying database engine, optimization should happen within PostgreSQL. Ensure you allocate appropriate values for shared_buffers, work_mem, and effective_cache_size within your PostgreSQL container configurations to comfortably handle heavy JSONB parsing loads.

---

Conclusion

Deploying FerretDB on a VPS offers a highly strategic middle ground for modern enterprises. It allows engineering teams to maximize development velocity using the familiar, flexible MongoDB API while anchoring the physical data layer into the industry-hardened, fully open-source ecosystem of PostgreSQL. By adopting this architecture, your business mitigates licensing risks, optimizes infrastructure expenditure, and maintains maximum flexibility over your data storage paradigms.