Databases Azure

mongo-express with FerretDB on Ubuntu 24.04 on Azure User Guide

| Product: mongo-express with FerretDB on Ubuntu 24.04 on Azure

Overview

This guide covers the deployment and use of mongo-express with FerretDB on Ubuntu 24.04 on Azure using cloudimg Azure Marketplace images.

The image bundles two open source tools that work together:

  • mongo-express (MIT) — the popular web based administration UI for MongoDB. It lets you browse databases, view and edit collections, insert, update and delete documents, run queries and inspect indexes, all from a browser.
  • FerretDB (Apache 2.0) — a truly open source database that speaks the MongoDB wire protocol while storing your data in PostgreSQL through the DocumentDB extension. Your existing MongoDB drivers and the mongosh shell work unchanged.

Why FerretDB rather than MongoDB Community Server: MongoDB Community is distributed under the Server Side Public License (SSPL), which is not freely redistributable in a paid marketplace image. FerretDB is a permissively licensed, MongoDB compatible alternative, so the whole stack in this image is open source and free of restrictive licensing. The datastore is FerretDB, backed by PostgreSQL — it is compatible with MongoDB, not MongoDB itself.

Security by design, no baked credential. Nothing in this image ships with a known password. On first boot each VM generates a unique database password (used by FerretDB to authenticate against PostgreSQL) and a unique web console password for mongo-express, and writes them to root only files. The MongoDB compatible endpoint is bound to loopback only, so only the local mongo-express reaches it; the web console is the single network facing service and is protected by HTTP basic authentication.

What is included:

  • mongo-express 1.0.2 running under systemd as mongo-express.service on port 8081, behind HTTP basic auth
  • FerretDB 2.7.0 running under systemd as ferretdb.service, MongoDB wire protocol on loopback 127.0.0.1:27017
  • PostgreSQL 17 with the DocumentDB extension as the storage backend (loopback only), running as postgresql.service
  • The mongosh MongoDB shell preinstalled
  • A demo database cloudimg_demo (a books collection with 5 documents and an authors collection) seeded on first boot, so the console shows real collections and documents immediately
  • A per VM web console password and a per VM database password generated on first boot, written to root only credentials files
  • No swap in the image; PostgreSQL is tuned to fit a Standard_B2s in RAM

Deploying the VM

Launch the image from the Azure Marketplace as you would any other VM. The recommended size is Standard_B2s (2 vCPU / 4 GiB), which the shipped configuration is tuned for.

The web console listens on TCP 8081. In the Azure network security group, open 8081 only to the client addresses that genuinely need it — never to the whole internet — and add 22 for SSH. The MongoDB compatible database on 27017 is bound to loopback and is deliberately not exposed.

First boot

On the first boot of each VM, two ordered one shot services run:

  1. ferretdb-firstboot.service generates a unique database password, creates the PostgreSQL role that FerretDB authenticates as, and writes /root/ferretdb-credentials.txt.
  2. mongo-express-firstboot.service generates a unique web console password, wires mongo-express to the database, seeds the cloudimg_demo demo database, and writes /root/mongo-express-credentials.txt.

Both complete within a few seconds of boot. You can confirm the whole stack is up:

systemctl status postgresql ferretdb mongo-express

Signing in to the web console

Retrieve the generated web console credentials (root only):

sudo cat /root/mongo-express-credentials.txt

You will see a username (cloudimg) and a unique password, plus the URL. Open the console in your browser:

http://<your-vm-public-ip>:8081/

Sign in with the basic auth username and password from the credentials file. The shipped default admin / pass credentials that mongo-express normally ships with are disabled — only the per VM password works.

Once signed in you will see the database list, including the seeded cloudimg_demo. Click View to open it, then open the books collection to browse its documents, or click a document to view and edit its JSON.

Connecting with the shell or a driver

The MongoDB compatible endpoint is on loopback port 27017. Retrieve the database password:

sudo cat /root/ferretdb-credentials.txt

Connect locally with the preinstalled shell and query the demo database. This reads the generated password straight from the credentials file, so you can run it as is:

DBPASS=$(sudo grep '^FERRETDB_PASSWORD=' /root/ferretdb-credentials.txt | cut -d= -f2-)
mongosh "mongodb://admin:${DBPASS}@127.0.0.1:27017/cloudimg_demo?authMechanism=SCRAM-SHA-256" \
  --quiet --eval 'print("Books in the Databases genre:"); db.books.find({genre:"Databases"}).forEach(d => print(" - " + d.title)); print("total books: " + db.books.countDocuments({}))'

To open an interactive shell instead, run mongosh "mongodb://admin:PASSWORD@127.0.0.1:27017/?authMechanism=SCRAM-SHA-256" with the password from the credentials file, then use commands such as use cloudimg_demo, db.books.find({ genre: "Databases" }) and db.books.countDocuments({}).

Any MongoDB driver works the same way — point its connection string at the endpoint using the admin user and the generated password.

Serving remote database clients

By default only the web console is reachable off box; the database stays on loopback. To let an external application connect directly to the database:

  1. Set FERRETDB_LISTEN_ADDR=0.0.0.0:27017 in /etc/ferretdb/ferretdb.env.
  2. sudo systemctl restart ferretdb.
  3. Open 27017 in the Azure network security group to your trusted client addresses only, and put TLS in front of it.

Do not expose 27017 to the internet without TLS.

Security notes

  • No default credential. Both the web console password and the database password are unique per VM, generated on first boot, and stored in root only files.
  • The console is your network surface. mongo-express on 8081 is the only service reachable off box. Restrict 8081 in the network security group to trusted addresses, and front it with a TLS terminating reverse proxy (or an Azure Application Gateway) for production use — basic auth over plain HTTP should only be used on a trusted network.
  • The database is loopback only unless you deliberately expose it as above.
  • Keep it patched. unattended-upgrades remains enabled, so the OS, PostgreSQL and Node.js receive security updates on your VM.
  • Rotate the credentials for anything beyond evaluation: change the PostgreSQL role password and update FERRETDB_POSTGRESQL_URL in /etc/ferretdb/ferretdb.env, and change ME_CONFIG_BASICAUTH_PASSWORD in /etc/mongo-express/mongo-express.env, then restart the affected service.

Compatibility notes

FerretDB implements the MongoDB wire protocol and is compatible with the great majority of MongoDB operations, drivers and tools, including mongo-express. It is an independent open source project and is not MongoDB Community Server. Some advanced or server specific MongoDB features may differ; see the FerretDB documentation for the current compatibility matrix.

Support

This image is published and supported by cloudimg. For help with the web console, connection strings and drivers, authentication, collections, indexes and queries, or the PostgreSQL and DocumentDB backend, contact cloudimg support.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them. MongoDB is a trademark of MongoDB, Inc.; this image ships FerretDB, an independent open source project, not MongoDB Community Server.