How To Install FerretDB on Linux Mint 22

If you’re running MongoDB in production and tired of its SSPL licensing restrictions, FerretDB is the open-source alternative you’ve been waiting for. This guide walks you through how to install FerretDB on Linux Mint 22 — from setting up the PostgreSQL backend to running live CRUD operations — so you can have a fully functional, production-ready MongoDB-compatible database server in under 30 minutes.

FerretDB acts as a stateless proxy that translates MongoDB wire protocol queries into SQL and stores everything in PostgreSQL as the backend engine. That means your existing MongoDB drivers, shell tools, and application code keep working without modification — while you gain the freedom of a truly open-source stack.

With FerretDB v2.0 GA (released March 2025), the project reached a major milestone: 20x performance improvements powered by Microsoft’s DocumentDB PostgreSQL extension, replication support via WAL streaming, vector search capabilities for AI workloads, and enterprise-grade support options. This is no longer a side project — it’s a production-grade database server.

Linux Mint 22 is built on Ubuntu 24.04 LTS, meaning it shares the same APT package ecosystem and .deb installation workflow. Every command in this tutorial works natively on Linux Mint 22 without hacks or workarounds.

Prerequisites

Before you begin this FerretDB on Linux Mint 22 setup, make sure your system and environment meet the following requirements:

• Operating System: Linux Mint 22 (64-bit, Ubuntu 24.04 LTS base)
• RAM: Minimum 2 GB (4 GB+ recommended for production)
• Disk Space: At least 10 GB free depending on your dataset size
• User Privileges: A non-root user account with sudo access
• Internet Access: Required to download packages from GitHub and APT repos
• Basic Knowledge: Familiarity with the Linux terminal, systemd, and basic SQL/database concepts
• Tools Needed: wget, dpkg or apt, nano or any text editor, mongosh (installed in Step 7)

Step 1: Update Your Linux Mint 22 System

Always start a Linux server tutorial by updating your package index and upgrading installed packages. This prevents dependency conflicts during installation.

sudo apt update
sudo apt upgrade -y

What this does: apt update refreshes the list of available packages from all configured repositories. apt upgrade -y installs the latest versions of all installed packages non-interactively.

Why it matters: Outdated packages can cause unresolved dependency errors when you install PostgreSQL or FerretDB later. A clean, fully updated system is the foundation of a stable installation.

Step 2: Install and Configure PostgreSQL

FerretDB does not store data on its own — it delegates all storage to PostgreSQL as its backend engine. This is the most critical dependency in the entire stack.

Install PostgreSQL

sudo apt install postgresql postgresql-contrib -y

postgresql-contrib includes extra extensions and utilities that PostgreSQL may use internally.

Verify and Enable PostgreSQL

psql --version
sudo systemctl status postgresql
sudo systemctl enable postgresql
sudo systemctl start postgresql

Expected output from psql --version:

psql (PostgreSQL) 16.x

If PostgreSQL is not yet running, the start command brings it online. The enable command ensures it automatically starts on every system reboot.

Create a Dedicated Database and User

Never connect FerretDB to PostgreSQL using the default postgres superuser. Create a dedicated role with minimal but sufficient privileges:

sudo -u postgres psql

Once inside the PostgreSQL prompt, run:

CREATE ROLE ferretuser WITH LOGIN PASSWORD 'your_secure_password';
CREATE DATABASE ferretdb;
GRANT ALL PRIVILEGES ON DATABASE ferretdb TO ferretuser;
\q

What each command does:

• CREATE ROLE — Creates a new PostgreSQL login user named ferretuser
• CREATE DATABASE ferretdb — Creates the database FerretDB will use for all document storage
• GRANT ALL PRIVILEGES — Gives ferretuser full read/write control over the ferretdb database
• \q — Exits the PostgreSQL prompt

Security tip: Replace your_secure_password with a strong, randomly generated password. Never reuse passwords across services.

Step 3: Download and Install FerretDB via DEB Package

The .deb package is the recommended installation method for all Debian and Ubuntu-based systems, including Linux Mint 22. It integrates natively with systemd and the APT ecosystem.

Find the Latest Release

Visit the official FerretDB GitHub Releases page to get the current version:

https://github.com/FerretDB/FerretDB/releases

Look for the file ending in _amd64.deb (for standard 64-bit systems).

Download the Package

wget https://github.com/FerretDB/FerretDB/releases/download/v2.x.x/ferretdb_2.x.x_amd64.deb -O ferretdb.deb

Replace v2.x.x with the actual current version number from the releases page.

Install the Package

sudo apt install ./ferretdb.deb

Using apt install instead of dpkg -i automatically resolves any missing dependencies.

Verify the Installation

ferretdb --version

Expected output:

version: v2.x.x

If you see the version string, the binary is installed correctly and available in your system PATH.

Step 4: Create a Dedicated System User for FerretDB

Running any service as root is a serious security risk. Create a restricted system user that owns and runs the FerretDB process:

sudo adduser --system --no-create-home --group ferretdb

What the flags mean:

• --system — Creates a system account with no password and no interactive login shell
• --no-create-home — Skips creating a home directory, since the service doesn’t need one
• --group — Creates a matching group with the same name ferretdb

This user will own the FerretDB process at runtime, limiting the blast radius of any potential security vulnerability.

Step 5: Configure FerretDB

Now that the binary is installed, give FerretDB a configuration file that tells it how to connect to PostgreSQL and which port to listen on.

Create the Configuration Directory

sudo mkdir -p /etc/ferretdb
sudo nano /etc/ferretdb/config.yml

Add the Configuration

Paste the following into the file, replacing the password with your actual PostgreSQL password:

handler: postgresql
postgresql:
  url: postgres://ferretuser:your_secure_password@localhost:5432/ferretdb
listen: 0.0.0.0:27017
debug: false

What each setting does:

Secure the Config File

The config file contains your database password. Restrict access immediately:

sudo chmod 640 /etc/ferretdb/config.yml
sudo chown root:ferretdb /etc/ferretdb/config.yml

This allows only root to write and ferretdb group members to read the file. World-readable config files with credentials are a common security misconfiguration.

Step 6: Set Up FerretDB as a systemd Service

Running FerretDB as a systemd service ensures it starts on boot, restarts on failure, and integrates cleanly with system logging.

Create the Service Unit File

sudo nano /etc/systemd/system/ferretdb.service

Paste the following content:

[Unit]
Description=FerretDB - A truly Open Source MongoDB alternative
After=network.target postgresql.service
Wants=postgresql.service

[Service]
Type=simple
User=ferretdb
Group=ferretdb
ExecStart=/usr/bin/ferretdb --config=/etc/ferretdb/config.yml
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=ferretdb

[Install]
WantedBy=multi-user.target

Section breakdown:

• [Unit] — Defines the service description and startup order. After=postgresql.service ensures PostgreSQL is running before FerretDB starts.
• [Service] — Defines how the process runs. Restart=on-failure automatically restarts FerretDB if it crashes unexpectedly.
• [Install] — Defines the boot target. multi-user.target means FerretDB starts during normal multi-user system boot.

Enable and Start the Service

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

Verify FerretDB is Running

sudo systemctl status ferretdb

Expected output:

● ferretdb.service - FerretDB - A truly Open Source MongoDB alternative
     Loaded: loaded (/etc/systemd/system/ferretdb.service; enabled)
     Active: active (running) since ...

The active (running) status confirms FerretDB is live and listening on port 27017.

Step 7: Install MongoDB Shell (mongosh)

FerretDB is fully compatible with the MongoDB wire protocol, so you use mongosh — the official MongoDB Shell — to interact with it.

wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo apt-key add -
echo "deb [ arch=amd64 ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list
sudo apt update
sudo apt install -y mongodb-mongosh

Verify the installation:

mongosh --version

Step 8: Connect to FerretDB and Verify — How To Install FerretDB on Linux Mint 22 End-to-End Test

This is the final validation step for your How To Install FerretDB on Linux Mint 22 setup.

Connect via mongosh

mongosh "mongodb://ferretuser:your_secure_password@localhost:27017/ferretdb?authMechanism=PLAIN"

Important: The authMechanism=PLAIN parameter is required for FerretDB’s PostgreSQL-backed authentication. Without it, the connection will fail with an auth error.

Expected connection output:

Current Mongosh Log ID: ...
Connecting to: mongodb://<credentials>@localhost:27017/ferretdb
Using MongoDB: 6.0.x
Using Mongosh: x.x.x
ferretdb>

Run Test CRUD Operations

Once connected, test each operation to confirm the full stack works end-to-end:

Insert:

use testdb
db.users.insertOne({ name: "Alice", role: "admin", active: true })

Read:

db.users.find()
db.users.findOne({ name: "Alice" })

Update:

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

Delete:

db.users.deleteOne({ name: "Alice" })

Each operation gets silently translated into a PostgreSQL SQL query by FerretDB behind the scenes. To confirm this, connect directly to PostgreSQL and inspect the ferretdb database — your documents will appear as rows inside PostgreSQL tables.

Step 9: Configure Firewall (Optional but Recommended)

If UFW (Uncomplicated Firewall) is active on your Linux Mint 22 machine, you need to allow traffic on port 27017:

sudo ufw status

For local-only access (safest):

sudo ufw allow from 127.0.0.1 to any port 27017
sudo ufw reload

For restricted remote access (allow only a specific client IP):

sudo ufw allow from 192.168.1.100 to any port 27017
sudo ufw reload

Never open port 27017 to 0.0.0.0/0 (the entire internet) without TLS encryption and strong authentication in place. This is one of the most common misconfigurations that leads to exposed database servers.

Troubleshooting Common Issues

Even with clean installations, things can go wrong. Here are the five most common issues and how to fix them.

Issue 1: FerretDB Service Fails to Start

Symptom: systemctl status ferretdb shows failed or activating indefinitely.

Solution: Check the service logs for the root cause:

sudo journalctl -u ferretdb -f

The most common cause is an incorrect PostgreSQL connection URL in config.yml. Double-check the username, password, host, port, and database name.

Issue 2: Cannot Connect via mongosh

Symptom: mongosh times out or returns connection refused.

Solution: First, confirm FerretDB is actually listening on port 27017:

ss -tlnp | grep 27017

If the port isn’t listed, FerretDB isn’t running. Check firewall rules with sudo ufw status and ensure authMechanism=PLAIN is in your connection string.

Issue 3: PostgreSQL Authentication Error

Symptom: psql: error: FATAL: peer authentication failed for user "ferretuser".

Solution: Edit the PostgreSQL client authentication config:

sudo nano /etc/postgresql/*/main/pg_hba.conf

Find the line for local connections and change the method from peer to scram-sha-256 or md5, then restart PostgreSQL:

sudo systemctl restart postgresql

Issue 4: DEB Package Install Errors

Symptom: dpkg throws errors about broken packages or missing dependencies.

Solution:

sudo apt install -f

This command fixes broken package states by installing missing dependencies. If the .deb file itself is corrupted, re-download it and verify the SHA256 checksum against the value listed on the GitHub release page.

Issue 5: Port 27017 Already in Use

Symptom: FerretDB starts but immediately exits because the port is occupied.

Solution: Find what’s using the port:

sudo lsof -i :27017

If a legacy MongoDB instance is running, stop it first: sudo systemctl stop mongod. Then start FerretDB. Alternatively, change FerretDB’s listen port in config.yml to something like 27018.

How to Upgrade FerretDB on Linux Mint 22

Keeping FerretDB up to date is important for security patches and new MongoDB compatibility improvements.

Step 1: Back Up the Database First

Always run a backup before any upgrade:

pg_dump -U ferretuser ferretdb > ferretdb_backup_$(date +%F).sql

Step 2: Stop, Install, and Restart

sudo systemctl stop ferretdb
wget https://github.com/FerretDB/FerretDB/releases/download/v2.x.x/ferretdb_2.x.x_amd64.deb -O ferretdb_new.deb
sudo apt install ./ferretdb_new.deb
sudo systemctl start ferretdb

Step 3: Verify the New Version

ferretdb --version
sudo systemctl status ferretdb

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