How To Install FerretDB on Debian 13

9 minutes read

Open-source databases have become the backbone of modern infrastructure, and the demand for MongoDB-compatible solutions without proprietary licensing constraints has never been higher. FerretDB fills that gap precisely — it is a fully open-source database proxy that translates MongoDB wire protocol queries into SQL, running on top of PostgreSQL as its storage engine. Whether you are migrating away from MongoDB or building a new application stack, FerretDB gives you compatibility without compromise.

This guide walks you through a complete, production-ready installation of FerretDB on Debian 13 “Trixie.” Every command is tested, every step is explained, and by the end you will have a running FerretDB instance connected to PostgreSQL and accessible via the MongoDB shell.

Table of Contents

What Is FerretDB?

FerretDB is an open-source MongoDB alternative licensed under Apache 2.0. Rather than reimplementing MongoDB from scratch, it acts as a translation layer — it accepts connections from any MongoDB-compatible client or driver and converts those operations into standard PostgreSQL queries on the backend.

Starting with FerretDB v2.x, the project uses the DocumentDB PostgreSQL extension (originally developed by Microsoft for Azure Cosmos DB) to handle BSON document storage directly within Postgres. This means you can use tools like mongosh, Compass, or any official MongoDB driver without modification, while your data stays safely inside a PostgreSQL database you fully control.

The practical result: zero licensing fees, true open-source ownership, and MongoDB API compatibility in one package.

Why Use Debian 13 Trixie as Your Server OS?

Debian 13 “Trixie” was released on August 9, 2025, and it represents one of the most significant Debian releases in years. For server workloads specifically, it ships with Linux Kernel 6.12 (with PREEMPT_RT patches for improved I/O latency), APT 3.0 for faster and more reliable package management, and default tmpfs mounting on /tmp for better temporary file performance.

Security hardening is also notably stronger — Intel CET and ARM PAC/BTI protections are enabled at the system level. For a database server that may handle sensitive application data, this matters. Debian’s conservative, stability-first release philosophy also means fewer surprises in production compared to rolling-release distributions.

Prerequisites

Before running a single command, confirm the following:

A Debian 13 “Trixie” server — physical hardware, a local VM, or a cloud VPS
Root access or a user with full sudo privileges
Minimum resources: 1 CPU core, 2 GB RAM, 10 GB free disk
Active internet connection for downloading packages
Basic familiarity with the Linux command line
Ports 27017 (FerretDB) and 5432 (PostgreSQL) not in use by other services
Packages available: curl, wget, gnupg, ca-certificates, apt-transport-https

Step 1: Update Your System Packages

Always start with a clean, fully updated system. This prevents dependency conflicts and ensures you are pulling packages against the latest repository metadata.

sudo apt update && sudo apt upgrade -y

The apt update command refreshes your local package index from all configured repositories. The apt upgrade -y flag applies all pending updates without prompting. If a kernel update is included, reboot the server before proceeding:

sudo reboot

Once the server is back online, reconnect via SSH and continue.

Step 2: Install PostgreSQL

FerretDB does not bundle its own storage engine — it delegates all persistence to PostgreSQL. You must install Postgres first and have it running before FerretDB can function.

Debian 13 ships PostgreSQL 15+ in its official repositories, so no external PPA or third-party repo is needed for a standard installation:

sudo apt install -y postgresql postgresql-contrib

The postgresql-contrib package adds extra functions and extensions that will be needed later. Once installed, verify the service is active:

sudo systemctl status postgresql

You should see Active: active (running) in the output. Enable PostgreSQL to start automatically on every boot:

sudo systemctl enable postgresql

Confirm the installed version:

psql --version

This returns something like psql (PostgreSQL) 15.x — note this version number, as you will need it when choosing the correct DocumentDB extension build.

Step 3: Install the DocumentDB Extension

This is the step most guides skip, and it is why many FerretDB v2.x installations fail silently. FerretDB v2+ requires the pg_documentdb extension to store BSON data inside PostgreSQL. Without it, FerretDB will start but will be unable to process document operations.

Download the correct .deb build from the official FerretDB/documentdb GitHub releases page. Match the PostgreSQL version on your system (e.g., pg17 or pg15):

wget https://github.com/FerretDB/documentdb/releases/download/<version>/documentdb-pg15_<version>_amd64.deb -O documentdb.deb
sudo dpkg -i documentdb.deb

Replace <version> with the actual release tag shown on the GitHub releases page. If dpkg reports missing dependencies, resolve them:

sudo apt --fix-broken install

Verify the extension is available to PostgreSQL:

sudo -u postgres psql -c "SELECT name, default_version FROM pg_available_extensions WHERE name LIKE '%documentdb%';"

If the extension appears in the output, you are ready to proceed to database configuration.

Step 4: Set Up the PostgreSQL Database and User

With PostgreSQL running and the DocumentDB extension installed, create a dedicated database and role for FerretDB. Using a dedicated role — rather than the default postgres superuser — is a security best practice for any production system.

Switch to the PostgreSQL system user and open the psql shell:

sudo -u postgres psql

Inside the shell, run the following commands one by one:

-- Create a dedicated login role
CREATE ROLE ferretuser WITH LOGIN PASSWORD 'YourStrongPassword';

-- Create the FerretDB database using UTF8 encoding
CREATE DATABASE ferretdb WITH ENCODING='UTF8' TEMPLATE=template0;

-- Grant full privileges on the database to the new role
GRANT ALL PRIVILEGES ON DATABASE ferretdb TO ferretuser;

-- Connect to the new database
\c ferretdb

-- Enable the DocumentDB extension
CREATE EXTENSION IF NOT EXISTS documentdb;

-- Exit psql
\q

Choose a strong, unique password and store it securely. This same password will appear in the FerretDB configuration file in the next step.

Step 5: Download the FerretDB DEB Package

Navigate to the official FerretDB GitHub Releases page at github.com/FerretDB/FerretDB/releases to identify the latest stable release. Always prefer stable releases over release candidates for server deployments.

Download the .deb package for linux_amd64 (the standard architecture for most Debian servers):

wget https://github.com/FerretDB/FerretDB/releases/download/v<version>/ferretdb_<version>_linux_amd64.deb -O ferretdb.deb

Before installing, verify the file downloaded correctly:

ls -lh ferretdb.deb

If the release page lists a SHA256 checksum file, verify the integrity of your download:

sha256sum ferretdb.deb

Compare the output against the published hash. Any mismatch means the file is corrupt or tampered with — re-download before continuing. This step takes ten seconds and eliminates a whole category of installation issues.

Step 6: Install FerretDB Using dpkg

With the .deb file downloaded and verified, install it using the Debian package manager:

sudo dpkg -i ferretdb.deb

If the installer reports unmet dependencies, run:

sudo apt --fix-broken install

Then retry the dpkg command. Once installation completes, confirm the binary is available:

ferretdb --version

This should return the FerretDB version string, confirming the binary is correctly installed in your system PATH. The .deb package also automatically registers a systemd unit file, meaning you can manage FerretDB like any other system service — no manual service configuration needed.

Step 7: Configure FerretDB

FerretDB reads its runtime configuration from a TOML file. Create the configuration directory and the file:

sudo mkdir -p /etc/ferretdb
sudo nano /etc/ferretdb/ferretdb.toml

Add the following configuration, replacing the password with the one you set in Step 4:

handler = "postgresql"
listen-addr = "0.0.0.0:27017"
postgresql-url = "postgres://ferretuser:YourStrongPassword@127.0.0.1:5432/ferretdb"
log-level = "info"

Here is what each directive does:

handler — Tells FerretDB which backend to use. postgresql is the correct value for a standard bare-metal setup.
listen-addr — The IP and port FerretDB listens on. Port 27017 is the MongoDB protocol default. Using 0.0.0.0 allows connections from any network interface; change this to 127.0.0.1 if only local connections are needed.
postgresql-url — The full PostgreSQL connection string pointing to the ferretdb database using the ferretuser role you created earlier.
log-level — Controls verbosity. info is a good default for production; use debug temporarily when troubleshooting.

Save the file with Ctrl+O, then exit with Ctrl+X.

Step 8: Enable and Start the FerretDB Service

With configuration in place, register and start the FerretDB service through systemd:

sudo systemctl daemon-reload
sudo systemctl enable ferretdb
sudo systemctl start ferretdb

The daemon-reload command tells systemd to re-read all unit files, including the one just installed by the FerretDB package. Enabling the service ensures it restarts automatically after a system reboot.

Check that the service came up cleanly:

sudo systemctl status ferretdb

Look for Active: active (running). If you see failed or activating, the issue is almost always in the postgresql-url — double-check for typos in the username, password, or database name.

One important note: FerretDB depends on the PostgreSQL service being available. If PostgreSQL is stopped or crashes, FerretDB will also fail. Always investigate both services together when diagnosing connectivity problems.

Step 9: Verify FerretDB Is Running

Confirm FerretDB is actively listening on port 27017:

ss -tlnp | grep 27017

Expected output shows the FerretDB process bound to 0.0.0.0:27017. Nothing here means the service did not bind — revisit the listen-addr in your config file.

Inspect recent log output for any startup warnings or errors:

sudo journalctl -u ferretdb -n 50 --no-pager

A healthy startup log includes a line similar to:

INFO Listening for connections  addr=0.0.0.0:27017

If you see PostgreSQL connection errors in the logs, the postgresql-url in your config is incorrect or the PostgreSQL service is not running.

Step 10: Install and Connect via mongosh

FerretDB is accessed using any standard MongoDB client. The recommended client is mongosh — the official MongoDB Shell.

Add the MongoDB APT repository to install mongosh on Debian 13:

sudo apt install -y gnupg curl

curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | \
  sudo gpg --dearmor -o /usr/share/keyrings/mongodb-server-7.0.gpg

echo "deb [arch=amd64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg] \
  https://repo.mongodb.org/apt/debian bookworm/mongodb-org/7.0 main" | \
  sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list

sudo apt update && sudo apt install -y mongodb-mongosh

Note: The repository uses bookworm (Debian 12) as the codename — this is expected and the packages install cleanly on Debian 13 Trixie.

Now connect to your FerretDB instance using the PostgreSQL credentials you configured:

mongosh "mongodb://ferretuser:YourStrongPassword@127.0.0.1:27017/ferretdb"

A successful connection displays output like:

Using MongoDB:    7.0.x
Using Mongosh:    2.x.x

ferretdb>

You are now connected to FerretDB through the standard MongoDB shell.

Step 11: Test Basic MongoDB Operations

Run a quick CRUD test to confirm the full stack — FerretDB, DocumentDB extension, and PostgreSQL — is working end-to-end.

Inside the mongosh prompt:

// Switch to a test database
use testdb

// Insert a document
db.users.insertOne({ name: "Alice", role: "admin", active: true })

// Query all documents
db.users.find()

// Update a document
db.users.updateOne({ name: "Alice" }, { $set: { role: "superadmin" } })

// Confirm the update
db.users.find({ name: "Alice" })

// Delete the document
db.users.deleteOne({ name: "Alice" })

Each operation should return a standard MongoDB-style JSON acknowledgment. The insertOne response includes an insertedId field; updateOne shows matchedCount and modifiedCount. If all four operations succeed without errors, your installation is fully functional.

Configuring UFW Firewall

If UFW (Uncomplicated Firewall) is active on your server, you need to explicitly allow access to port 27017 — but only from trusted sources. Never expose this port to the open internet without authentication and TLS encryption in place.

To allow connections from a specific application server IP:

sudo ufw allow from <trusted_IP> to any port 27017
sudo ufw reload
sudo ufw status

Keep port 5432 (PostgreSQL) restricted to localhost only. FerretDB communicates with PostgreSQL internally — there is no reason to expose the Postgres port externally under any normal deployment scenario.

Troubleshooting Common Issues

Most installation problems fall into a small number of categories.

FerretDB service fails to start
Check whether PostgreSQL is running first: sudo systemctl status postgresql. Then verify the postgresql-url in /etc/ferretdb/ferretdb.toml for typos in the hostname, username, password, or database name.

Port 27017 not listening
Confirm the listen-addr setting in the config file. Restart FerretDB after any config change: sudo systemctl restart ferretdb.

Authentication failed in mongosh
The username or password in your connection string does not match the PostgreSQL role. Re-check what was set in Step 4 and update the config file if needed.

extension “documentdb” not found
This means Step 3 was skipped or the extension was not enabled inside the correct database. Re-run CREATE EXTENSION IF NOT EXISTS documentdb; while connected to the ferretdb database in psql.

dpkg reports unmet dependencies
Run sudo apt --fix-broken install after the failed dpkg command, then retry installation.

How to Update FerretDB

Keeping FerretDB current ensures access to bug fixes, compatibility improvements, and new MongoDB API support. The update process is straightforward but follows a specific order.

Always update the DocumentDB PostgreSQL extension first, then FerretDB. Updating FerretDB before the extension can cause incompatibility errors at runtime.

Download the new DocumentDB .deb from the FerretDB/documentdb releases page and install it
Download the new FerretDB .deb from the FerretDB/FerretDB releases page
Install with dpkg:
```
sudo dpkg -i /path/to/new-ferretdb.deb
```
Verify the version: ferretdb --version
Restart the service: sudo systemctl restart ferretdb

Check the official changelog at docs.ferretdb.io before upgrading in production to review any breaking changes or new configuration requirements.

Congratulations! You have successfully installed FerretDB. Thanks for using this tutorial for installing the FerretDB open-source MongoDB alternative on Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the official FerretDB website.

VPS Manage Service Offer

If you don’t have time to do all of this stuff, or if this is not your area of expertise, we offer a service to do “VPS Manage Service Offer”, starting from $10 (Paypal payment). Please contact us to get the best deal!