Guides

FerretDB

This guide shows you how to use FerretDB an open-source proxy that translates MongoDB wire protocol queries to SQL.

To run it, follow these steps:

1. Install the kraft CLI tool and a container runtime engine, e.g. Docker.

2. Clone the examples repository.

   Code
    
   git clone https://github.com/kraftcloud/examples

   We will use both the postgres16.2/ example and the ferretdb/ example.

Make sure to log into Unikraft Cloud by setting your token and a metro close to you. We use fra0 (Frankfurt, 🇩🇪) in this guide:

Code
 
# Set Unikraft Cloud access token
export UKC_TOKEN=token
# Set metro to Frankfurt, DE
export UKC_METRO=fra0

We will deploy FerretDB as a frontend and PostgreSQL as a backend and run them together inside a service. For that, follow these steps:

1. Run an instance of PostgreSQL using the postgres16.2/ example:

   Code
    
   cd postgres16.2/
   kraft cloud deploy -M 1024 -e POSTGRES_PASSWORD=unikraft --name postgres .

2. Run an instance of FerretDB:

   Code
    
   cd ../ferretdb/
   kraft cloud deploy -M 512 -p 27017:27017/tls -e FERRETDB_HANDLER=pg -e FERRETDB_POSTGRESQL_URL=postgres://postgres.internal:5432 -e FERRETDB_LISTEN_ADDR=0.0.0.0:27017 .

Code
 
[●] Deployed successfully!
 │
 ├────────── name: ferretdb-rdj6z
 ├────────── uuid: 0b18a36d-9d43-4907-833d-7242f0e75f78
 ├───────── state: running
 ├────────── fqdn: restless-resonance-jcc4ulc3.fra0.kraft.host
 ├───────── image: ferretdb@sha256:27c59539fa3b6b7d2948ee4ceb2ceb75309328a9055a394bf949bede96aa7e27
 ├───── boot time: 37.11 ms
 ├──────── memory: 512 MiB
 ├─────── service: restless-resonance-jcc4ulc3
 ├── private fqdn: ferretdb-rdj6z.internal
 ├──── private ip: 172.16.3.5
 └────────── args: /usr/bin/ferretdb

In this case, the instance name is ferretdb-rdj6z; it's different for each run.

To test the deployment, first forward the port with the kraft cloud tunnel command:

Code
 
kraft cloud tunnel 27017:memcached-arkv7:27017

Then, on a separate console, you can use the mongosh client to connect to the server using the postgres username and the unikraft password configured above:

Code
 
mongosh mongodb://postgres:unikraft@127.0.0.1?authMechanism=PLAIN

You should see output similar to:

Code
 
Current Mongosh Log ID: 660ad7329a710d16355bedf4
Connecting to:          mongodb://<credentials>@127.0.0.1/?authMechanism=PLAIN&directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.1.1
Using MongoDB:          7.0.42
Using Mongosh:          2.1.1
mongosh 2.2.2 is available for download: https://www.mongodb.com/try/download/shell

For mongosh info see: https://docs.mongodb.com/mongodb-shell/

------
   The server generated these startup warnings when booting
   2024-04-01T15:48:02.365Z: Powered by FerretDB v1.21.0 and PostgreSQL 16.2 on x86_64-pc-linux-musl, compiled by gcc.
   2024-04-01T15:48:02.365Z: Please star us on GitHub: https://github.com/FerretDB/FerretDB.
   2024-04-01T15:48:02.365Z: The telemetry state is undecided.
   2024-04-01T15:48:02.365Z: Read more about FerretDB telemetry and how to opt out at https://beacon.ferretdb.com.
------

test>

To disconnect, simply kill the tunnel command with ctrl-C

At any point in time, you can list information about the PostgreSQL and FerretDB instances:

Code
 
kraft cloud instance list

Code
 
NAME                          FQDN                                         STATE    CREATED AT      IMAGE                               MEMORY   ARGS                                         BOOT TIME
ferretdb-rdj6z                restless-resonance-jcc4ulc3.fra0.kraft.host  running  11 minutes ago  ferretdb@sha256:27c59539fa3b6b7...  512 MiB  /usr/bin/ferretdb                            37.11 ms
postgres                                                                   running  14 minutes ago  postgres@sha256:c1f1100176be97f...  1.0 GiB  wrapper.sh docker-entrypoint.sh postgres     593.15 ms

When done, you can remove the FerretDB and the Postgres instances:

Code
 
kraft cloud instance remove ferretdb-rdj6z
kraft cloud instance remove postgres

Customize Your Deployment

There are several ways in which you can customize your deployment.

An obvious one is to use a different database password when starting PostgreSQL. For that you use a different POSTGRES_PASSWORD environment variable when starting the PosgreSQL instance.

Another one is to use volumes with PostgreSQL for persistence. For that, you would first create a volume:

Code
 
kraft cloud volume create --name ferret-postgres --size 200

And then, when, starting the PostgreSQL instance, you would attach the volume to a mount point:

Code
 
kraft cloud deploy -M 1024 -e POSTGRES_PASSWORD=unikraft -e PGDATA=/volume/postgres --name postgres -v ferret-postgres:/volume .

Learn More

Use the --help option for detailed information on using Unikraft Cloud:

Code
 
kraft cloud --help

Or visit the CLI Reference.