How To Install FerretDB on Fedora 41

FerretDB stands as a promising open-source alternative to MongoDB, offering compatibility with MongoDB’s wire protocol while using PostgreSQL or SQLite as the underlying storage engine. This approach allows developers to leverage MongoDB’s flexible document-oriented interface without concerns about licensing restrictions or vendor lock-in. For Fedora 41 users looking to implement a document database solution, FerretDB provides an excellent option that combines the familiarity of MongoDB with the reliability of PostgreSQL.

This guide walks you through the complete process of installing and configuring FerretDB on Fedora 41. We’ll cover everything from setting up prerequisites to advanced configuration options, ensuring you have a fully functional and optimized FerretDB deployment. Whether you’re a database administrator, a developer, or simply exploring MongoDB-compatible alternatives, this tutorial will equip you with the knowledge needed to successfully implement FerretDB in your environment.

Understanding FerretDB

FerretDB (formerly known as MongoBridge) is an open-source proxy that translates MongoDB wire protocol commands into SQL, allowing standard relational databases to serve as the backend for applications designed to work with MongoDB. By functioning as a “MongoDB without MongoDB,” FerretDB enables users to work with familiar MongoDB tools and drivers while storing data in PostgreSQL or SQLite.

The project aims to provide compatibility with MongoDB 5.0+ while offering freedom from potential vendor lock-in concerns. FerretDB’s architecture consists of a translation layer that converts MongoDB queries and commands into SQL operations that PostgreSQL can understand. This approach allows developers to continue using the document-oriented model of MongoDB while benefiting from PostgreSQL’s mature, reliable storage engine.

Key features of FerretDB include:

• MongoDB API compatibility for seamless integration with existing applications
• Support for CRUD operations, aggregation pipelines, and indexes
• No requirement for MongoDB licenses or subscriptions
• Active development with regular updates and improvements
• Growing community support and contributions

FerretDB provides particular advantages for organizations seeking to avoid the licensing restrictions of MongoDB’s Server Side Public License (SSPL) while maintaining compatibility with MongoDB-based applications. By leveraging PostgreSQL’s proven reliability and performance, FerretDB offers a compelling alternative for document database needs on Fedora 41 systems.

Prerequisites

Before beginning the FerretDB installation process on Fedora 41, ensure your system meets the following requirements:

System Requirements:

• Fedora 41 (minimal or workstation edition)
• 2 GB RAM minimum (4 GB recommended for production use)
• 2 CPU cores (4+ recommended for production environments)
• 10 GB free disk space (more for database storage)
• Internet connection for downloading packages

User Privileges:
You’ll need sudo/root access to install packages and configure system services. Most commands in this tutorial require elevated privileges, so be prepared to enter your password when prompted.

Basic Skills:

• Familiarity with terminal/command line operations
• Basic understanding of Linux file permissions
• Rudimentary knowledge of database concepts

Before proceeding with any significant system changes, it’s always recommended to back up any important data. While the installation process is generally safe, having a backup provides protection against unexpected issues.

Finally, ensure your Fedora system has updated package repositories and the latest system updates installed. This helps avoid compatibility issues and ensures you have the most secure versions of all dependencies.

Setting Up Fedora 41 Environment

Preparing your Fedora 41 system for FerretDB installation involves several important steps to ensure a smooth deployment process. Start by updating your system to the latest package versions:

sudo dnf update -y

Next, install the essential development tools and dependencies that will be required during the installation process:

sudo dnf install -y dnf-plugins-core
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y wget curl git

Configure the firewall to allow the necessary ports for FerretDB and PostgreSQL. By default, PostgreSQL uses port 5432, and FerretDB typically operates on port 27017 (the standard MongoDB port):

sudo firewall-cmd --permanent --add-port=27017/tcp
sudo firewall-cmd --permanent --add-port=5432/tcp
sudo firewall-cmd --reload

If SELinux is enabled on your system (which is the default in Fedora), you may need to configure it to allow the necessary connections:

sudo dnf install -y policycoreutils-python-utils
sudo semanage port -a -t postgresql_port_t -p tcp 27017

This command tells SELinux to treat port 27017 as a PostgreSQL-related port, which should allow FerretDB to communicate properly. If you encounter permission issues later, you may need to create custom SELinux policies or temporarily set SELinux to permissive mode for testing purposes.

Finally, verify that your system is ready for the next steps:

sudo systemctl status firewalld
sudo sestatus

These commands confirm that your firewall is active and display the current SELinux status. With these preparations complete, your Fedora 41 environment is ready for PostgreSQL installation.

Installing PostgreSQL on Fedora 41

FerretDB requires a PostgreSQL database as its storage backend. Fedora 41 makes PostgreSQL installation straightforward through the default repositories. Follow these steps to install and configure PostgreSQL:

First, install the PostgreSQL server and client packages:

sudo dnf install -y postgresql postgresql-server postgresql-contrib

After installation, initialize the PostgreSQL database cluster:

sudo postgresql-setup --initdb

Now, start the PostgreSQL service and enable it to start automatically on system boot:

sudo systemctl start postgresql
sudo systemctl enable postgresql

Verify that PostgreSQL is running correctly:

sudo systemctl status postgresql

The output should indicate that the service is active and running. Next, let’s secure the PostgreSQL installation by setting a password for the default postgres user:

sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'your_secure_password';"

Replace ‘your_secure_password’ with a strong, unique password. Make note of this password, as you’ll need it for configuring FerretDB later.

To verify your PostgreSQL installation is working properly, connect to the PostgreSQL server using the psql client:

sudo -u postgres psql

You should see the PostgreSQL command prompt (postgres=#). Type \q to exit.

At this point, you have a basic PostgreSQL installation ready on your Fedora 41 system. The next step is to configure PostgreSQL specifically for FerretDB’s requirements.

Configuring PostgreSQL for FerretDB

With PostgreSQL installed, we need to configure it specifically for FerretDB by creating a dedicated database and user, and modifying access permissions appropriately.

First, create a new database user and database for FerretDB:

sudo -u postgres psql -c "CREATE USER ferretdb WITH PASSWORD 'ferretdb_password';"
sudo -u postgres psql -c "CREATE DATABASE ferretdb OWNER ferretdb;"

Replace ‘ferretdb_password‘ with a secure password. This creates a PostgreSQL user named ‘ferretdb‘ and a database also named ‘ferretdb‘, with the user set as the database owner.

Next, grant the necessary privileges to the ferretdb user:

sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE ferretdb TO ferretdb;"

For FerretDB to communicate with PostgreSQL, we need to modify PostgreSQL’s configuration files. First, edit the postgresql.conf file:

sudo nano /var/lib/pgsql/data/postgresql.conf

Find the line that begins with listen_addresses and modify it to:

listen_addresses = 'localhost'

If your FerretDB will run on a different host, you may need to set this to the server’s IP address or ‘*’ to allow connections from any address (not recommended for production without additional security measures).

Next, configure the client authentication settings in pg_hba.conf:

sudo nano /var/lib/pgsql/data/pg_hba.conf

Add the following line near the end of the file, before any other host lines:

host    ferretdb        ferretdb        127.0.0.1/32            md5
host    ferretdb        ferretdb        ::1/128                 md5

This configuration allows the ferretdb user to connect to the ferretdb database from localhost using password authentication.

After making these changes, restart PostgreSQL to apply them:

sudo systemctl restart postgresql

To verify your configuration, test connecting to the new database as the ferretdb user:

psql -h localhost -U ferretdb -d ferretdb

You should be prompted for the ferretdb user’s password. After entering it, you should see the PostgreSQL prompt. Type \q to exit.

With PostgreSQL properly configured, you’re now ready to install FerretDB itself.

Downloading and Installing FerretDB

FerretDB can be installed through several methods, including package managers, binary downloads, or building from source. For Fedora 41, we’ll focus on the RPM package installation method, which provides the simplest and most reliable approach.

First, download the latest FerretDB RPM package. Visit the official FerretDB releases page to find the latest version. As of this writing, you would use a command like:

wget https://github.com/FerretDB/FerretDB/releases/download/v1.X.X/ferretdb-1.X.X-1.fc41.x86_64.rpm

Replace 1.X.X with the current version number. If there isn’t a specific Fedora 41 package available, you may need to use a package for a similar version or build from source.

Next, install the downloaded RPM package:

sudo dnf install -y ./ferretdb-1.X.X-1.fc41.x86_64.rpm

If the RPM installation method isn’t available, you can download the binary release directly:

wget https://github.com/FerretDB/FerretDB/releases/download/v1.X.X/ferretdb-linux-amd64.tar.gz
sudo tar -xzf ferretdb-linux-amd64.tar.gz -C /usr/local/bin/
sudo chmod +x /usr/local/bin/ferretdb

After installation, verify that FerretDB is correctly installed:

ferretdb --version

This should display the installed FerretDB version. The FerretDB installation typically creates these important directories:

• /etc/ferretdb/ – Configuration files
• /var/lib/ferretdb/ – Data directory
• /var/log/ferretdb/ – Log files

If these directories don’t exist, you may need to create them manually:

sudo mkdir -p /etc/ferretdb /var/lib/ferretdb /var/log/ferretdb

Now that FerretDB is installed, the next step is to configure it to work with your PostgreSQL database.

Basic FerretDB Configuration

Proper configuration is crucial for FerretDB to operate effectively with PostgreSQL on your Fedora 41 system. We’ll start by creating a basic configuration file:

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

Add the following basic configuration to the file:

handler: "postgresql"
postgresql:
  uri: "postgres://ferretdb:ferretdb_password@localhost:5432/ferretdb"

listen: "0.0.0.0:27017"
debug: false

log:
  level: "info"
  format: "text"

Make sure to replace ferretdb_password with the actual password you set for the ferretdb PostgreSQL user earlier. Let’s examine the key configuration parameters:

• handler: Specifies the database backend (postgresql in our case)
• postgresql.uri: The connection string for PostgreSQL
• listen: The address and port where FerretDB will listen for connections
• debug: Enables or disables debug mode
• log: Controls logging behavior

For better security in production environments, consider changing the listen parameter to bind only to specific network interfaces rather than all interfaces (0.0.0.0).

Save the file and exit the editor. Next, create a directory for FerretDB data and set appropriate permissions:

sudo mkdir -p /var/lib/ferretdb
sudo chown -R $(whoami):$(whoami) /var/lib/ferretdb

To test the configuration, run FerretDB manually:

ferretdb --config /etc/ferretdb/ferretdb.yaml

If everything is configured correctly, you should see log messages indicating that FerretDB started successfully and is listening for connections. Press Ctrl+C to stop the manual FerretDB process.

This basic configuration should be sufficient for testing, but we’ll cover more advanced options in a later section. For now, let’s move on to setting up FerretDB as a system service.

Creating a SystemD Service

To ensure FerretDB starts automatically when your Fedora 41 system boots and is properly managed as a system service, we’ll create a SystemD service file:

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

Add the following configuration to the file:

[Unit]
Description=FerretDB MongoDB Alternative
After=network.target postgresql.service
Requires=postgresql.service

[Service]
Type=simple
User=ferretdb
Group=ferretdb
ExecStart=/usr/bin/ferretdb --config /etc/ferretdb/ferretdb.yaml
Restart=always
RestartSec=10
LimitNOFILE=65535
TimeoutStartSec=120

[Install]
WantedBy=multi-user.target

This service configuration ensures that:

• FerretDB starts after the network and PostgreSQL services
• The service runs as a dedicated user for better security
• The process will automatically restart if it crashes
• Appropriate file descriptor limits are set for performance

Before starting the service, create a dedicated system user for running FerretDB:

sudo useradd -r -s /bin/false ferretdb
sudo chown -R ferretdb:ferretdb /etc/ferretdb /var/lib/ferretdb /var/log/ferretdb

Now reload the SystemD configuration to recognize the new service:

sudo systemctl daemon-reload

Start the FerretDB service and enable it to start automatically on boot:

sudo systemctl start ferretdb
sudo systemctl enable ferretdb

To verify that the service is running correctly:

sudo systemctl status ferretdb

You should see output indicating that the service is active and running. To examine the service logs:

sudo journalctl -u ferretdb -f

This command shows the live logs for the FerretDB service. Press Ctrl+C to exit the log view.

If you encounter any issues with the service starting, check the logs for error messages that might indicate configuration problems:

sudo journalctl -u ferretdb -e

With the SystemD service properly configured, FerretDB will start automatically when your system boots and restart if it crashes, providing a reliable service for your applications.

Advanced Configuration Options

After establishing a basic FerretDB setup, you might want to explore advanced configuration options to enhance security, performance, and compatibility. Here are some important advanced settings you can add to your /etc/ferretdb/ferretdb.yaml file:

Authentication Configuration:

FerretDB supports MongoDB’s authentication mechanisms. To enable authentication:

mongodb:
  auth:
    enabled: true

TLS/SSL Configuration:

For encrypted connections, configure TLS/SSL:

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

Connection Pooling:

Optimize PostgreSQL connection handling:

postgresql:
  uri: "postgres://ferretdb:password@localhost:5432/ferretdb"
  pool:
    max_open_conns: 50
    max_idle_conns: 10
    conn_max_lifetime: "1h"

Query Timeout Settings:

Set limits on query execution time:

timeout:
  query: "30s"

Advanced Logging Options:

Configure detailed logging for troubleshooting:

log:
  level: "debug"
  format: "json"
  file: "/var/log/ferretdb/ferretdb.log"

Compatibility Modes:

Enable specific MongoDB compatibility features:

compatibility:
  allow_dropping_non_existing_collections: true
  allow_dropping_system_collections: false

After making any changes to the configuration file, restart the FerretDB service to apply them:

sudo systemctl restart ferretdb

Remember to verify the configuration changes by checking the service logs:

sudo journalctl -u ferretdb -n 50

These advanced configuration options allow you to tailor FerretDB to your specific requirements, balancing performance, security, and compatibility with MongoDB applications. As FerretDB continues to evolve, additional configuration options may become available, so it’s worth periodically checking the official documentation for updates.

Testing the FerretDB Installation

After installing and configuring FerretDB, it’s essential to verify that it’s working correctly by testing its MongoDB compatibility. First, install the MongoDB Shell (mongosh), which is the standard client for interacting with MongoDB-compatible databases:

sudo dnf install -y mongosh

If mongosh isn’t available in the standard repositories, you can download it from the MongoDB website:

wget https://downloads.mongodb.com/compass/mongosh-1.X.X-x86_64.rpm
sudo dnf install -y ./mongosh-1.X.X-x86_64.rpm

Once mongosh is installed, connect to your FerretDB instance:

mongosh mongodb://localhost:27017

If you’ve configured authentication, use:

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

After connecting, run some basic operations to test functionality:

1. Create a test collection:

use testdb
db.createCollection("testcollection")

2. Insert a document:

db.testcollection.insertOne({name: "Test Document", value: 123})

3. Query the collection:

db.testcollection.find()

4. Update the document:

db.testcollection.updateOne({name: "Test Document"}, {$set: {value: 456}})

5. Verify the update:

db.testcollection.find()

6. Delete the document:

db.testcollection.deleteOne({name: "Test Document"})

To verify that FerretDB is actually storing data in PostgreSQL, connect to PostgreSQL and examine the tables:

sudo -u postgres psql -d ferretdb -c "\dt"

You should see tables created by FerretDB to store your collections and documents. To examine the actual data:

sudo -u postgres psql -d ferretdb -c "SELECT * FROM _ferretdb_database_testdb_collection_testcollection;"

The table name format follows FerretDB’s naming convention for PostgreSQL storage.

These tests confirm that your FerretDB installation is correctly accepting MongoDB commands and storing the data in PostgreSQL. If all operations succeed, your FerretDB installation is working properly.

Securing Your FerretDB Deployment

Implementing proper security measures is crucial for protecting your FerretDB deployment on Fedora 41. Here are essential steps to secure your installation:

Network Security:

Limit FerretDB’s accessibility by binding it to specific network interfaces rather than all interfaces:

listen: "127.0.0.1:27017"  # Only listen on localhost

If external access is required, use your firewall to restrict access to trusted IP addresses:

sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="192.168.1.0/24" port port="27017" protocol="tcp" accept'
sudo firewall-cmd --reload

Authentication:

Always enable authentication for production deployments by adding users to your FerretDB instance:

use admin
db.createUser({
  user: "adminUser",
  pwd: "securePassword",
  roles: [ { role: "root", db: "admin" } ]
})

Then enable authentication in your FerretDB configuration:

mongodb:
  auth:
    enabled: true

Encryption:

For data in transit, configure TLS/SSL as mentioned in the advanced configuration section. Generate proper certificates or use Let’s Encrypt for trusted certificates.

Regular Updates:

Keep FerretDB, PostgreSQL, and Fedora updated with security patches:

sudo dnf update -y

Monitoring:

Set up monitoring to detect unusual activities:

sudo dnf install -y auditd
sudo systemctl enable auditd
sudo systemctl start auditd

Add audit rules to monitor access to FerretDB configuration and data files:

sudo auditctl -w /etc/ferretdb/ -p wa -k ferretdb_config
sudo auditctl -w /var/lib/ferretdb/ -p wa -k ferretdb_data

PostgreSQL Security:

Secure the underlying PostgreSQL database:

sudo nano /var/lib/pgsql/data/pg_hba.conf

Ensure only necessary connections are allowed and password authentication is enforced.

Regular Backups:

Implement a backup strategy for your PostgreSQL database:

sudo -u postgres pg_dump ferretdb > ferretdb_backup.sql

Consider automating backups with a cron job:

echo "0 2 * * * sudo -u postgres pg_dump ferretdb > /backup/ferretdb_$(date +\%Y\%m\%d).sql" | sudo tee -a /etc/crontab

By implementing these security measures, you’ll significantly reduce the risk of unauthorized access or data loss in your FerretDB deployment. Remember that security is an ongoing process—regularly review and update your security measures as new recommendations become available.

Troubleshooting Common Issues

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

Connection Issues:

If you can’t connect to FerretDB using MongoDB clients:

1. Verify the service is running:

sudo systemctl status ferretdb

2. Check if FerretDB is listening on the expected port:

sudo ss -tulpn | grep 27017

3. Ensure firewall rules allow connections:

sudo firewall-cmd --list-all

4. Test local connectivity first:

mongosh mongodb://localhost:27017

Authentication Problems:

If you’re experiencing authentication failures:

1. Verify you’re using the correct credentials

2. Check FerretDB logs for authentication errors:

sudo journalctl -u ferretdb | grep auth

3. Reset the user password if necessary:

use admin
db.changeUserPassword("username", "newpassword")

PostgreSQL Connection Errors:

If FerretDB can’t connect to PostgreSQL:

1. Verify PostgreSQL is running:

sudo systemctl status postgresql

2. Check the connection string in ferretdb.yaml

3. Ensure the PostgreSQL user has proper permissions:

sudo -u postgres psql -c "SELECT rolname, rolcanlogin FROM pg_roles WHERE rolname='ferretdb';"

4. Verify PostgreSQL is accepting connections:

sudo -u postgres psql -c "SHOW listen_addresses;"
sudo -u postgres psql -c "SELECT * FROM pg_hba_file_rules;"

Performance Issues:

If you’re experiencing slow queries:

1. Check system resources:

top
free -h
df -h

2. Examine PostgreSQL performance:

sudo -u postgres psql -c "SELECT * FROM pg_stat_activity;"

3. Review FerretDB logs for slow operations:

sudo journalctl -u ferretdb | grep -i slow

SELinux-Related Problems:

If SELinux is blocking FerretDB operations:

1. Check SELinux status:

sestatus

2. View SELinux denials:

sudo ausearch -m avc -ts recent

3. Create a custom policy or temporarily set SELinux to permissive mode for testing:

sudo setenforce 0  # Temporary until reboot

If you encounter persistent issues, consult the FerretDB logs for detailed error messages:

sudo journalctl -u ferretdb -e

For community support, visit the FerretDB GitHub repository issues section or join their community forums. Most issues can be resolved by carefully examining log messages and verifying configuration settings.

Performance Tuning

Optimizing your FerretDB deployment on Fedora 41 can significantly improve performance for your applications. Here are key areas to focus on for performance tuning:

PostgreSQL Optimization:

PostgreSQL is the foundation of FerretDB’s storage, so optimizing it has a direct impact on performance:

1. Adjust memory parameters in postgresql.conf:

sudo nano /var/lib/pgsql/data/postgresql.conf

Key settings to modify:

shared_buffers = 256MB          # Increase for more caching (25% of RAM)
work_mem = 16MB                 # Increase for complex queries
maintenance_work_mem = 64MB     # For maintenance operations
effective_cache_size = 768MB    # Set to ~50-75% of available RAM

2. Optimize write performance:

wal_buffers = 16MB              # Increase for write-heavy workloads
checkpoint_timeout = 15min      # Less frequent checkpoints
checkpoint_completion_target = 0.9

System-Level Tuning:

1. Adjust Linux swappiness for database servers:

echo "vm.swappiness = 10" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

2. Configure transparent huge pages for database workloads:

echo never | sudo tee /sys/kernel/mm/transparent_hugepage/enabled

3. Set I/O scheduler for SSDs:

echo "deadline" | sudo tee /sys/block/sda/queue/scheduler

FerretDB Configuration:

Optimize FerretDB’s connection pooling and timeouts:

postgresql:
  pool:
    max_open_conns: 100        # Increase for high concurrency
    max_idle_conns: 25
    conn_max_lifetime: "30m"

timeout:
  query: "60s"                 # Adjust based on query complexity

Query Optimization:

1. Create appropriate indexes for frequent queries:

db.collection.createIndex({ field: 1 })

2. Analyze slow queries in PostgreSQL:

sudo -u postgres psql -d ferretdb -c "SELECT * FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 10;"

Monitoring Performance:

Install monitoring tools to track system and database performance:

sudo dnf install -y prometheus node_exporter grafana

Configure PostgreSQL for monitoring:

shared_preload_libraries = 'pg_stat_statements'
pg_stat_statements.track = all

Remember that performance optimization is an iterative process. Monitor your system under real workloads, identify bottlenecks, make incremental changes, and measure the impact of each change. The optimal configuration depends on your specific workload, hardware, and application requirements.

For high-performance deployments, consider scaling options like read replicas for PostgreSQL or sharding your data across multiple FerretDB instances.

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