MongoDB Atlas

MongoDB Atlas and Koyeb

MongoDB Atlas (opens in a new tab) 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:

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.

Deploy to Koyeb (opens in a new tab)

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

Create a MongoDB Atlas cluster

To create a MongoDB Atlas cluster, first log in to your account, 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. We will keep this option disabled since we are only interested in demonstrating the process in this guide.
  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 authentication for the cluster. We have two options:

  1. Using a username and password
  2. Using a certificate for password-less authentication

We will use the first option which will create 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. In the next step, we will show how to connect your MongoDB Atlas cluster to an application running on Koyeb.

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:


Save it in a safe place. We will need it in the next step to connect our application to the database.

Deploy the application on Koyeb

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

To deploy the example application (opens in a new tab) using the control panel (opens in a new tab), follow these steps:

  1. Click Create Web Service on the Overview tab of the Koyeb control panel.
  2. Select GitHub as the deployment option.
  3. Set as the GitHub repository to deploy.
  4. Expand the Builder section. Click the override toggle associated with the Build command and enter npm run mongodb:init in the field.
  5. In the Regions section, choose was, the Washington, D.C region.
  6. Expand the Environment variables section. Add a DATABASE_URL environment variable to tell the application how to connect to the MongoDB cluster. Give the environment variable the name DATABASE_URL and enter the connection string from earlier as the value.
  7. Name your App and Service, for instance, express-mongodb.
  8. Click the Deploy button.

A Koyeb App and Service will be created. Your application will be built and deployed to Koyeb. Once the build has finished, you will be able to access your application running on Koyeb by clicking the URL ending with

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

    "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: