MongoDB Atlas and Koyeb

MongoDB Atlas is a fully-managed cloud database solution that provides a simple way to deploy, operate, and scale MongoDB databases in the cloud.

This guide explains how to connect your MongoDB Atlas cluster to an application running on Koyeb. To successfully follow this documentation, you will need to have:

• A Koyeb account to deploy the application. You can optionally install the Koyeb CLI if you prefer to follow this guide without leaving the terminal
• A Mongo DB Atlas account to deploy the MongoDB cluster

If you already have a MongoDB cluster running and want to quickly preview how to connect your MongoDB cluster to an application running on Koyeb, use the Deploy to Koyeb button below.

Make sure to replace properly set the DATABASE_URL environment variable with the connection string of your MongoDB cluster.

Create a MongoDB Atlas cluster

To create a MongoDB Atlas cluster, once you log in, select the organization and find the project you want to use. Then, click on the Build a Database button.

1. Select the cluster type to deploy and click the Create button. In this documentation, we will create a Shared cluster
2. Choose the Cloud Provider and Region where you want to deploy your cluster. Here, we select AWS and the region us-east-1 as our Koyeb service will be deployed in this region
3. Select the cluster tier of your choice. In our case the M0 Sandbox cluster tier.
4. In the additional settings section, depending on your needs, you can choose to turn on backup. As this documentation is here to showcase how to connect a MongoDB Atlas cluster to a Koyeb service, we will keep the option disabled
5. To prevent accidentally deleting the cluster, we strongly recommend you to enable the Termination Protection
6. Give the cluster a name, e.g. mongodb-koyeb

Once you have completed the cluster configuration, click on the Create Cluster button.

Configure MongoDB Atlas authentication

Next, we need to configure how to authenticate the connection to the cluster. We have two options:

1. Using a username and password
2. Using a certificate for passwordless authentication

We will use the first option which will create a user using a username and password.

1. Fill the username input with the username you want to use to connect to the cluster, e.g. koyeb
2. Click the Autogenerate Secure Password button to generate the password. Copy and save it in a safe place as you will need it to connect to the cluster
3. Click the Create Database User button to create the user

With the user created, we are now ready to connect to the cluster and can move to the next step where we will show how to connect your MongoDB Atlas cluster to an application running on Koyeb.

Prepare the database on your machine

The application we will deploy on Koyeb to connect to the MongoDB cluster uses Prisma as an ORM. Prisma is an open-source ORM. We use it to synchronize our database schema with our Prisma schema.

Before deploying the application, we will need to perform a migration to create the database schema and seed data.

Clone the example application

Start by cloning the example application that will connect to the MongoDB Atlas cluster on your machine and navigate to the directory by running the following commands:

git clone git@github.com:koyeb/example-express-prisma.git
cd example-express-prisma
git checkout mongodb

Retrieve your MongoDB Atlas connection string

On the MongoDB Database Deployments page, click on the Connect button of the cluster you created. A modal open and ask you to choose the connection method. Select Connect your application and copy the connection string similar to the following:

mongodb+srv://<user>:<password>@<host>/?retryWrites=true&w=majority

Initialize and seed the database

To synchronize our database schema with our Prisma schema and seed data, run the following commands in your terminal:

DATABASE_URL="mongodb+srv://<user>:<password>@<host>/<database-name>?retryWrites=true&w=majority" npx prisma db push
DATABASE_URL="mongodb+srv://<user>:<password>@<host>/<database-name>?retryWrites=true&w=majority" npx prisma db seed

*Make sure to replace user, password, host, and database-name with your own.

Deploy the application on Koyeb

You can deploy on Koyeb using the control panel or via the Koyeb CLI.

Via the Koyeb control panel

To deploy the example application using the control panel, follow these steps:

1. Create a new Koyeb App
2. Setgithub.com/koyeb/example-express-prisma as the GitHub repository to deploy and select the mongodb branch
3. Choose the Washington, D.C region was
4. Add a DATABASE_URL environment variable to indicate the application how to connect to the MongoDB cluster. Give the environment variable a name, DATABASE_URL and enter the connection string from earlier as the value
5. Name your service, for instance, express-mongodb
6. Click the Create service button

Koyeb is now building the application. Once the build has finished, you will be able to access your application running on Koyeb by clicking the URL ending with .koyeb.app.

The example application exposes a /planets endpoint that you can use to list planets from the database we prepared earlier. Once your deployment is live, you should see the following results when navigating to https://<YOUR_APP_URL>.koyeb.app/planets:

[
  {
    "id": "63cef0c77cc8d4d669448fe0",
    "name": "Mercury"
  },
  {
    "id": "63cef0c87cc8d4d669448fe1",
    "name": "Venus"
  },
  {
    "id": "63cef0c87cc8d4d669448fe2",
    "name": "Mars"
  }
]

Via the Koyeb CLI

To deploy the example application using the Koyeb CLI, run the following command in your terminal:

koyeb app init express-mongodb \
--git github.com/koyeb/example-express-prisma \
--git-branch mongodb \
--ports 8080:http \
--routes /:8080 \
--env PORT=8080 \
--region was \
--env DATABASE_URL="mongodb+srv://<user>:<password>@<host>/mongodb-koyeb?retryWrites=true&w=majority"

Make sure to replace user, password, and host with your own.

Access deployment logs

To track the app deployment and visualize build logs, execute the following command:

koyeb service logs express-mongodb/express-mongodb -t build

Access your app

Once the deployment of your application has finished, you can retrieve the public domain to access your application by running the following command:

$ koyeb app get express-mongodb
ID      	NAME                  	STATUS  	DOMAINS                                      	CREATED AT
b60982b7	express-mongodb       	STARTING	["express-mongodb-ed.koyeb.app"]	            24 Jan 23 10:06 UTC

The example application exposes a /planets endpoint that you can use to list planets from the database we prepared earlier. Once your deployment is live, you should see the following results when navigating to https://<YOUR_APP_URL>.koyeb.app/planets:

[
  {
    "id": "827696777012871169",
    "name": "Mercury"
  },
  {
    "id": "827696777225666561",
    "name": "Venus"
  },
  {
    "id": "827696777389539329",
    "name": "Mars"
  },
]

Delete the example application and MongoDB cluster

To delete the example application and the MongoDB cluster and avoid incurring any charges, follow these steps:

• From the MongoDB Atlas dashboard, click the more button icon of the cluster you created and click Terminate. Follow the instructions
• From the Koyeb control panel, select the App to delete. Under the Settings tab, click the Delete button and follow the instructions