Install & Configure MongoDB on the Raspberry Pi
Mark SmithPublished Feb 07, 2022 • Updated Sep 23, 2022
Rate this tutorial
I've been a big fan of the Raspberry Pi since the first version was released in 2012. The newer generations are wonderful home-automation and IoT prototyping computers, with built in WiFi, and the most recent versions (the Pi 3 and Pi 4) are 64-bit. This means they can run the MongoDB server, mongod, locally! MongoDB even provides a pre-compiled version for the Raspberry Pi processor, so it's relatively straightforward to get it installed.
I'm currently building a home-automation service on a Raspberry Pi 4. Its job is to run background tasks, such as periodically requesting data from the internet, and then provide the data to a bunch of small devices around my house, such as some smart displays, and (ahem) my coffee grinder.
The service doesn't have super-complex data storage requirements, and I could have used an embedded database, such as SQLite. But I've become resistant to modelling tables and joins in a relational database and working with flat rows. The ability to store rich data structures in a single MongoDB database is a killer feature for me.
You will need:
- A Raspberry Pi 3 or 4
- A suitably sized Micro SD card (I used a 16 Gb card)
- A computer and SD card reader to write the SD card image. (This can be another Raspberry Pi, but I'm using my desktop PC)
- A text editor on the host computer. (I recommend VS Code)
This tutorial will show you how to:
- Install the 64-bit version of Ubuntu Server on your Raspberry Pi.
- Configure it to connect to your WiFi.
- Correctly install MongoDB onto your Pi.
- Add a user account, so you can safely expose MongoDB on your home network.
When you're done, you'll have a secured MongoDB instance available on your home network.
Before we get too far into this, please bear in mind that you don't want to run a production, web-scale database on a Raspberry Pi. Despite the processor improvements on the Pi 4, it's still a relatively low-powered machine, with a relatively low amount of RAM for a database server. Still! For a local, offline MongoDB instance, with the ease of development that MongoDB offers, a Raspberry Pi is a great low-cost solution. If you do wish to serve your data to the Internet, you should definitely check out Atlas, MongoDB's cloud hosting solution. MongoDB will host your database for you, and the service has a generous (and permanent) free tier!
Do not run
apt install mongodbon your Raspberry Pi, or indeed any Linux computer! The versions of MongoDB shipped with Linux distributions are very out of date. They won't run as well, and some of them are so old they're no longer supported.
MongoDB provide versions of the database, pre-packaged for many different operating systems, and Ubuntu Server on Raspberry Pi is one of them.
Download and install the Raspberry Pi Imager for your host computer.
Run the Raspberry Pi Imager, and select Ubuntu Server 20.04, 64-bit for Raspberry Pi 3/4.
Make sure you don't accidentally select Ubuntu Core, or a 32-bit version.
Insert your Micro SD Card into your computer and select it in the Raspberry Pi Imager window.
Click Write and wait for the image to be written to the SD Card. This may take some time! When it's finished, close the Raspberry Pi Imager. Then remove the Micro SD Card from your computer, and re-insert it.
The Ubuntu image for Raspberry Pi uses cloud-init to configure the system at boot time. This means that in your SD card
system-bootvolume, there should be a YAML file, called
network-config. Open this file in VS Code (or your favourite text editor).
Edit it so that it looks like the following. The indentation is important, and it's the 'wifis' section that you're editing to match your wifi configuration. Replace 'YOUR-WIFI-SSD' with your WiFi's name, and 'YOUR-WIFI-PASSWORD' with your WiFi password.
Now eject the SD card (safely!) from your computer, insert it into the Pi, and power it up! It may take a few minutes to start up, at least the first time. You'll need to monitor your network to wait for the Pi to connect. When it does, ssh into the Pi with
ssh ubuntu@<raspberry-pi-ip-address>. The password is also
You'll be prompted to change your password to something secret.
Once you've set your password update the operating system by running the following commands:
Now let's install MongoDB. This is done as follows:
The instructions above have mostly been taken from Install MongoDB Community Edition on Ubuntu
Ubuntu 20.04 uses Systemd to run background services, so to set up mongod to run in the background, you need to enable and start the service:
Now, you can check to see if the service is running correctly by executing the following command. You should see something like the output below it:
If your service is running correctly, you can run the MongoDB client,
mongo, from the command-line to connect:
First, check the warnings. You can ignore the recommendation to run the XFS filesystem, as this is just a small, local install. The warning about access control not being enabled for the database is important though! You'll fix that in the next section. At this point, if you feel like it, you can enable the free monitoring that MongoDB provides, by running
db.enableFreeMonitoring()inside the mongo shell.
Here's the next, essential steps, that other tutorials miss out, for some reason. Recent versions of mongod won't connect to the network unless user authentication has been configured. Because of this, at the moment your database is only accessible from the Raspberry Pi itself. This may actually be fine, if like me, the services you're running with MongoDB are running on the same device. It's still a good idea to set a username and password on the database.
Here's how you do that, inside
mongo(replace SUPERSECRETPASSWORD with an actual secret password!):
The three roles listed give the
adminuser the ability to administer all user accounts and data in MongoDB. Make sure your password is secure. You can use a random password generator to be safe.
Now you need to reconfigure mongod to run with authentication enabled, by adding a couple of lines to
/etc/mongod.conf. If you're comfortable with a terminal text editor, such as vi or emacs, use one of those. I used nano, because it's a little simpler, with
sudo nano /etc/mongod.conf. Add the following two lines somewhere in the file. Like the
network-configfile you edited earlier, it's a YAML file, so the indentation is important!
And finally, restart mongod:
Ensure that authentication is enforced by connecting
Ensure you've exited
mongoand now test that you can connect and authenticate with the user details you created:
This step is optional! Now that you've configured authentication on your server, if you want your database to be available to other computers on your network, you need to:
- Bind MongoDb to the Raspberry Pi's public IP address
- Open up port
27017on the Raspberry Pi's firewall.
If you don't want to access your data from your network, don't follow these steps! It's always better to leave things more secure, if possible.
/etc/mongod.confagain, the same way as before. This time, change the IP address to 0.0.0.0:
Open up port 27017 on your Raspberry Pi's firewall:
Now, on another computer on your network, with the MongoDB client installed, run the following to ensure that
mongodis available on your network:
If it connects, then you've successfully installed and configured MongoDB on your Raspberry Pi!
This short section is extremely important. Don't skip it.
- Never open up an instance of
mongodto the internet without authentication enabled.
- Configure your firewall to limit the IP addresses which can connect to your MongoDB port. (Your Raspberry Pi has just been configured to allow connections from anywhere, with the assumption that your home network has a firewall blocking access from outside.)
- Ensure the database user password you created is secure!
- Set up different database users for each app that connects to your database server, with only the permissions required by each app.
MongoDB comes with sensible security defaults. It uses TLS, SCRAM-based password authentication, and won't bind to your network port without authentication being set up. It's still up to you to understand how to secure your Raspberry Pi and any data you store within it. Go and read the MongoDB Security Checklist for further information on keeping your data secure.
As you can see, there are a few steps to properly installing and configuring MongoDB yourself. I hadn't done it for a while, and I'd forgotten how complicated it can be! For this reason, you should definitely consider using MongoDB Atlas where a lot of this is taken care of for you. Not only is the free-forever tier quite generous for small use-cases, there are also a bunch of extra services thrown in, such as serverless functions, charting, free-text search, and more!
You're done! Go write some code in your favourite programming language, and if you're proud of it (or even if you're just having some trouble and would like some help) let us know!. Check out all the cool blog posts on the MongoDB Developer Hub, and make sure to bookmark MongoDB Documentation