How To Install FerretDB on Ubuntu 24.04 LTS

FerretDB is a truly open-source alternative to MongoDB that allows you to run MongoDB commands and queries using PostgreSQL or SQLite as the backend. As Ubuntu 24.04 LTS (Noble Numbat) is now available, many developers are looking to deploy FerretDB on this latest Ubuntu version. This comprehensive guide will walk you through the entire installation process, configuration options, and best practices for running FerretDB on Ubuntu 24.04 LTS.

Understanding FerretDB

FerretDB positions itself as a truly open-source alternative to MongoDB. It functions as a stateless proxy that converts MongoDB wire protocol queries into SQL and uses PostgreSQL with DocumentDB extension as its underlying database engine. This architecture allows applications to use the MongoDB protocol and BSON format to communicate with FerretDB, which then translates these requests into PostgreSQL protocol and SQL queries.

The development of FerretDB was motivated by MongoDB’s shift away from its open-source roots when it changed to the SSPL license, making it unusable for many open-source and early-stage commercial projects. FerretDB fills this gap by providing an easy-to-use open-source document database solution that maintains compatibility with MongoDB drivers and popular MongoDB tools, serving as a drop-in replacement for MongoDB 5.0+ in many scenarios.

As a proxy between MongoDB clients and PostgreSQL, FerretDB enables developers to continue using familiar MongoDB commands, drivers, and tools while leveraging PostgreSQL’s robust and mature database infrastructure. This approach provides several advantages, including freedom from vendor lock-in, the ability to use well-established PostgreSQL tools for database management, and compliance with truly open-source licensing.

FerretDB is particularly valuable for developers who appreciate MongoDB’s document-oriented approach but prefer to stay within the open-source ecosystem. It’s designed to be compatible with MongoDB 5.0+ wire protocol, making it suitable for many applications that don’t require MongoDB’s advanced proprietary features. The project is actively developed with features constantly being added to increase compatibility and performance, with a public roadmap available on GitHub.

Prerequisites for Installing FerretDB

Before proceeding with the installation of FerretDB on Ubuntu 24.04 LTS, ensure that your system meets the following requirements:

For optimal performance, your system should have at least 2GB of RAM and adequate disk space, especially if you’re planning to deploy in a production environment. These requirements are similar to those for running MongoDB itself.

You’ll need a user account with sudo privileges to perform the installation steps. This is essential for installing packages and configuring system services. It’s also recommended to have a basic understanding of Linux commands, database concepts, and MongoDB query language to effectively work with FerretDB after installation.

Since FerretDB uses PostgreSQL as its backend, familiarity with PostgreSQL administration can be helpful but isn’t strictly necessary for basic usage. The installation process will guide you through setting up PostgreSQL appropriately.

Before starting the installation, it’s good practice to ensure your system is up-to-date. Update your package lists and upgrade existing packages by running:

sudo apt update
sudo apt upgrade

This ensures that you have the latest security patches and dependencies required for FerretDB and PostgreSQL.

Installation Methods Overview

FerretDB offers several installation methods to accommodate different use cases and preferences. The primary installation methods include using Docker containers, DEB packages for Debian-based systems like Ubuntu, RPM packages for RHEL-based systems, and building from source.

For Ubuntu 24.04 LTS users, the most straightforward approaches are using Docker or installing the DEB package. Docker provides a quick way to get started without modifying your system extensively, while the DEB package installation offers better integration with the Ubuntu system and potential performance benefits.

This guide will cover both methods in detail, along with instructions for building from source for users who need maximum customization options.

Method 1: Installing FerretDB Using Docker

Docker provides the simplest way to get started with FerretDB, offering a containerized environment that isolates the application from your system. This method is ideal for testing, development, or when you want to quickly evaluate FerretDB without making permanent changes to your system.

First, ensure Docker is installed on your Ubuntu 24.04 system:

sudo apt update
sudo apt install docker.io
sudo systemctl enable --now docker

To verify the Docker installation, run:

docker --version

For FerretDB, there are several Docker images available. The simplest option for testing is the all-in-one image that includes FerretDB, PostgreSQL with DocumentDB extension, and MongoDB Shell:

docker run -d --rm --name ferretdb -p 27017:27017 --platform linux/amd64 ghcr.io/ferretdb/ferretdb-eval:2

This command starts a container with FerretDB exposed on port 27017, making it accessible just like a regular MongoDB instance. However, this image is intended for quick testing and experimentation only, as it keeps all data inside the container and loses it when the container is shut down.

For a more production-ready setup, you can use FerretDB with a separate PostgreSQL container:

# Create a network for the containers
docker network create ferretdb-network

# Start PostgreSQL container
docker run -d --name postgres --network ferretdb-network -e POSTGRES_PASSWORD=password postgres:16

# Start FerretDB container
docker run -d --name ferretdb --network ferretdb-network -p 27017:27017 -e FERRETDB_POSTGRESQL_URL=postgres://postgres:password@postgres:5432/ferretdb ghcr.io/ferretdb/ferretdb:latest

This setup connects FerretDB to a separate PostgreSQL container, allowing for better data persistence and management. The FerretDB container connects to PostgreSQL using the connection string specified in the FERRETDB_POSTGRESQL_URL environment variable.

To verify your installation, you can connect to FerretDB using any MongoDB client, such as mongosh:

mongosh mongodb://localhost:27017

You should now be able to perform basic MongoDB operations through FerretDB, which will translate them to PostgreSQL operations behind the scenes.

Method 2: Installing FerretDB Using DEB Package

For a more integrated installation with your Ubuntu 24.04 LTS system, you can install FerretDB using the DEB package. This method provides better system integration and potentially better performance than containerized solutions.

Step 1: Install PostgreSQL

Since FerretDB uses PostgreSQL as its backend, you need to install PostgreSQL first:

sudo apt update
sudo apt install postgresql postgresql-contrib

Verify that PostgreSQL is installed correctly by checking its version:

psql --version

Step 2: Create a database and user for FerretDB

Before using FerretDB, you need to create a dedicated database and user in PostgreSQL:

# Connect to PostgreSQL as the postgres user
sudo -u postgres psql

# Create a new user for FerretDB
CREATE ROLE ferretuser WITH LOGIN PASSWORD 'your_password';

# Create a database for FerretDB
CREATE DATABASE ferretdb;

# Grant privileges to the user
GRANT ALL PRIVILEGES ON DATABASE ferretdb TO ferretuser;

# Exit PostgreSQL
\q

These commands create a PostgreSQL user named ‘ferretuser‘ with the specified password and a database named ‘ferretdb‘, then grant the user full privileges on that database.

Step 3: Download and install FerretDB

Download the latest DEB package for FerretDB from the official repository:

# Download the FerretDB DEB package
wget https://github.com/FerretDB/FerretDB/releases/download/v1.x.x/ferretdb_1.x.x_amd64.deb

Replace `v1.x.x` with the latest version available. Then install the package:

sudo apt install ./ferretdb_1.x.x_amd64.deb

Step 4: Configure FerretDB

After installation, you need to configure FerretDB to connect to your PostgreSQL database. Create a configuration file:

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

Add the following configuration, adjusting values as needed:

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

This configuration sets FerretDB to use PostgreSQL as the backend with the database and user created earlier, and makes FerretDB listen on all interfaces on port 27017.

Step 5: Start FerretDB

Create a systemd service file for FerretDB:

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

Add the following content to create the service:

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

[Service]
ExecStart=/usr/bin/ferretdb --config=/etc/ferretdb/config.yml
Restart=on-failure
User=ferretdb
Group=ferretdb

[Install]
WantedBy=multi-user.target

Create a system user for running FerretDB:

sudo adduser --system --group ferretdb

Then, start and enable the FerretDB service:

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

Verify that FerretDB is running by checking its status:

sudo systemctl status ferretdb

Method 3: Building FerretDB from Source

For users who want the most control over their FerretDB installation or need to make custom modifications, building from source is an option. This method requires more technical knowledge but provides maximum flexibility.

Step 1: Install build dependencies

First, install the necessary build dependencies:

sudo apt update
sudo apt install git golang-go build-essential postgresql postgresql-contrib

Go (Golang) is required as FerretDB is written in Go. Verify your Go installation:

go version

Ensure you have Go version 1.18 or higher for compatibility with FerretDB’s codebase.

Step 2: Clone the FerretDB repository

Clone the FerretDB repository from GitHub:

git clone https://github.com/FerretDB/FerretDB.git
cd FerretDB

Step 3: Build FerretDB

Build FerretDB using the provided build tools:

make build

This command compiles FerretDB and creates an executable binary in the `bin` directory.

Step 4: Configure PostgreSQL

Just as with the DEB package installation, you need to create a PostgreSQL database and user for FerretDB:

sudo -u postgres psql

CREATE ROLE ferretuser WITH LOGIN PASSWORD 'your_password';
CREATE DATABASE ferretdb;
GRANT ALL PRIVILEGES ON DATABASE ferretdb TO ferretuser;

\q

Step 5: Create a configuration file

Create a configuration file for FerretDB:

mkdir -p ~/.config/ferretdb
nano ~/.config/ferretdb/config.yml

Add the following configuration:

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

Step 6: Run FerretDB

You can now run FerretDB using the built binary:

./bin/ferretdb --config=~/.config/ferretdb/config.yml

To run FerretDB as a service, create a systemd service file as described in the DEB package installation method, but adjust the ExecStart path to point to your built binary.

Building from source offers advantages such as being able to use the latest code, making custom modifications, and optimizing the build for your specific environment. However, it requires more technical knowledge and manual maintenance for updates.

Configuring FerretDB

Proper configuration is essential for optimizing FerretDB’s performance and security. The primary configuration file for FerretDB is typically located at `/etc/ferretdb/config.yml` for system-wide installations or in the user’s configuration directory for source installations.

Basic Configuration Parameters

The most important configuration parameters include:

1. Handler: Specifies the backend database type. Currently, PostgreSQL and SQLite are supported:

handler: postgresql

2. PostgreSQL Connection URL: Defines how FerretDB connects to PostgreSQL:

postgresql:
  url: postgres://username:password@hostname:5432/database

3. Listen Address: Specifies the IP address and port FerretDB listens on:

listen: 0.0.0.0:27017

4. Debug Mode: Enables or disables debug logging:

debug: false

Security Considerations

For production environments, consider implementing the following security measures:

1. Bind to Specific Interface: Instead of binding to all interfaces (`0.0.0.0`), bind to specific interfaces or localhost if FerretDB is only accessed locally.

2. Use TLS/SSL: Configure TLS/SSL for encrypted connections:

tls:
certificate: /path/to/cert.pem
key: /path/to/key.pem

3. Authentication: Implement MongoDB-compatible authentication mechanisms to secure access to your FerretDB instance.

4. Network Security: Use firewalls to restrict access to the FerretDB port (default 27017).

Performance Tuning

To optimize FerretDB’s performance:

1. Connection Pooling: Adjust PostgreSQL’s connection pooling settings for better performance under high loads.
2. Index Optimization: Create appropriate indexes in PostgreSQL to accelerate queries processed by FerretDB.
3. Resource Allocation: Allocate sufficient memory and CPU resources to PostgreSQL, which performs the actual data storage and retrieval operations.
4. Query Optimization: Be aware of which MongoDB queries translate efficiently to SQL and which might have performance implications when processed by FerretDB.

Remember that FerretDB is still under active development, and performance characteristics may differ from native MongoDB in certain scenarios. Regular monitoring and tuning are recommended for production deployments.

Setting Up FerretDB as a Systemd Service

For a production environment, running FerretDB as a systemd service ensures it starts automatically at boot and can be managed easily using standard system tools. This section builds upon the service file created during the DEB package installation method.

Creating a Complete Systemd Service File

If you haven’t already created a service file, create one at `/etc/systemd/system/ferretdb.service`:

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

Add the following content, adjusting paths as needed for your installation method:

[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
Environment=

[Install]
WantedBy=multi-user.target

This service configuration ensures that FerretDB starts after the network and PostgreSQL services are available, runs as the dedicated ferretdb user, and automatically restarts if it fails.

Managing the FerretDB Service

After creating the service file, reload the systemd configuration:

sudo systemctl daemon-reload

Start the FerretDB service:

sudo systemctl start ferretdb

Enable the service to start automatically at boot:

sudo systemctl enable ferretdb

Check the status of the service:

sudo systemctl status ferretdb

To stop or restart the service:

sudo systemctl stop ferretdb
sudo systemctl restart ferretdb

Viewing Service Logs

You can view the FerretDB service logs using journalctl:

sudo journalctl -u ferretdb

To follow the logs in real-time:

sudo journalctl -u ferretdb -f

These logs are valuable for troubleshooting and monitoring the FerretDB service.

Testing FerretDB Installation

After successfully installing FerretDB, it’s important to verify that it’s working correctly. You can test your installation using any MongoDB client, as FerretDB is designed to be compatible with the MongoDB wire protocol.

Connecting with MongoDB Shell

The most straightforward way to test FerretDB is using the MongoDB Shell (mongosh):

mongosh mongodb://localhost:27017

If you’ve configured authentication, include the credentials:

mongosh mongodb://username:password@localhost:27017

Basic CRUD Operations

Once connected, test basic CRUD (Create, Read, Update, Delete) operations:

1. Creating a collection and inserting documents:

use testdb
db.createCollection("users")
db.users.insertOne({name: "Meilana Maria", email: "Meilana@example.com"})
db.users.insertMany([
  {name: "Meilana Maria", email: "Meilana@example.com"},
  {name: "Nadia Shell", email: "Nadia@example.com"}
])

2. Reading documents:

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

3. Updating documents:

db.users.updateOne({name: "John Doe"}, {$set: {age: 30}})
db.users.updateMany({}, {$set: {active: true}})

4. Deleting documents:

db.users.deleteOne({name: "Bob Johnson"})

If all these operations work successfully, your FerretDB installation is functioning correctly. Note that while FerretDB aims to be compatible with MongoDB, there may be some differences in behavior or unsupported features, which are documented in the FerretDB documentation.

Advanced Configuration and Usage

As you become more familiar with FerretDB, you may want to explore advanced configurations and usage patterns to optimize your deployment for specific workloads and requirements.

Working with PostgreSQL Directly

Since FerretDB uses PostgreSQL as its backend, you can leverage PostgreSQL’s native tools and capabilities alongside FerretDB. For example, you can access the PostgreSQL database directly to:

1. Perform complex SQL queries that might be more efficient than their MongoDB equivalents
2. Set up fine-grained PostgreSQL-level permissions
3. Implement PostgreSQL-specific optimizations

To connect to the PostgreSQL backend:

psql -U ferretuser -d ferretdb

Inside PostgreSQL, you’ll find that FerretDB organizes MongoDB collections as schemas, with documents stored in tables. This hybrid approach gives you the flexibility of MongoDB’s document model with PostgreSQL’s robustness.

Monitoring and Performance Optimization

For production deployments, implement comprehensive monitoring:

1. Use PostgreSQL monitoring tools like pg_stat_statements to identify slow queries
2. Monitor system resources (CPU, memory, disk I/O) to identify bottlenecks
3. Set up alerting for critical metrics

Performance optimization strategies include:

1. Implementing appropriate PostgreSQL indexing strategies
2. Adjusting PostgreSQL configuration parameters for your workload
3. Optimizing your MongoDB queries to translate efficiently to SQL

Backup and Recovery

Implement a robust backup strategy using PostgreSQL’s native tools:

1. Regular pg_dump backups:

pg_dump -U ferretuser ferretdb > ferretdb_backup.sql

2. Point-in-time recovery using WAL archiving

3. Automated backup scheduling with tools like cron

Scaling Considerations

As your application grows, consider these scaling approaches:

1. Vertical scaling: Increase resources (CPU, RAM) on your PostgreSQL server
2. Connection pooling with pgBouncer to handle more concurrent connections
3. Read replicas for read-heavy workloads
4. Partitioning large collections/tables for improved performance

Remember that FerretDB’s performance characteristics may differ from native MongoDB, particularly for very large datasets or high-concurrency scenarios, so regular monitoring and tuning are essential.

Troubleshooting Common Issues

Even with a careful installation process, you might encounter issues with your FerretDB deployment. Here are solutions to common problems:

Connection Issues

If you can’t connect to FerretDB:

1. FerretDB not running: Check the service status with `sudo systemctl status ferretdb` and start it if necessary.

2. Firewall blocking connections: Verify that port 27017 is accessible:

sudo ufw status

If needed, allow the port:

sudo ufw allow 27017/tcp

3. Binding to wrong interface: Ensure FerretDB is binding to the correct interface in your config.yml file.

4. PostgreSQL connection failures: Verify that PostgreSQL is running and accessible:

sudo systemctl status postgresql

Authentication Problems

If you encounter authentication issues:

1. PostgreSQL authentication: Verify the PostgreSQL credentials in your FerretDB configuration. Test direct connection to PostgreSQL:

psql -U ferretuser -d ferretdb

2. MongoDB authentication: If you’ve configured MongoDB-style authentication in FerretDB, verify the credentials and authentication database.

Performance Issues

For performance-related problems:

1. Slow queries: Identify slow queries in the PostgreSQL logs and create appropriate indexes.
2. Resource constraints: Check system resources using tools like `top` or `htop` to identify CPU, memory, or disk bottlenecks.
3. Connection limits: If you’re hitting connection limits, adjust PostgreSQL’s `max_connections` parameter.

Upgrading FerretDB

As FerretDB continues to evolve with new features and improvements, you’ll need to keep your installation up-to-date. Here’s how to upgrade FerretDB while minimizing downtime and ensuring data integrity.

Before Upgrading

1. Back up your data: Always create a backup of your PostgreSQL database before upgrading:

pg_dump -U ferretuser -d ferretdb > ferretdb_backup_before_upgrade.sql

2. Review the changelog: Check the release notes for the new version to understand changes, especially breaking changes or new dependencies.

3. Test in a non-production environment: If possible, test the upgrade process in a development or staging environment first.

Upgrading Docker Installation

For Docker-based installations, upgrading is straightforward:

1. Pull the latest image:

docker pull ghcr.io/ferretdb/ferretdb:latest

2. Stop and remove the existing container:

docker stop ferretdb
docker rm ferretdb

3. Start a new container with the updated image, using the same configuration.

Upgrading DEB Package Installation

For DEB package installations:

1. Download the new DEB package:

wget https://github.com/FerretDB/FerretDB/releases/download/v1.x.x/ferretdb_1.x.x_amd64.deb

2. Stop the FerretDB service:

sudo systemctl stop ferretdb

3. Install the new package:

sudo apt install ./ferretdb_1.x.x_amd64.deb

4. Start the service:

sudo systemctl start ferretdb

Upgrading Source Installation

For source installations:

1. Navigate to your FerretDB directory:

cd FerretDB

2. Pull the latest code:

git pull

3. Rebuild:

make build

4. Restart the service or process.

Post-Upgrade Verification

After upgrading, verify that FerretDB is working correctly by:

1. Checking the service status
2. Connecting with a MongoDB client
3. Running basic CRUD operations to ensure functionality

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