MongoDB Atlas and Koyeb

Integrate a managed MongoDB Atlas database to your application and benefit from native autoscaling, automatic HTTPS (SSL), auto-healing, and global load-balancing across our edge network with zero configuration.

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:

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

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, you 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. 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.

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.

Via the Koyeb control panel

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

  1. Create a new Koyeb App
  2. as the GitHub repository to deploy and keep the default branch main
  3. Set npm run mongodb:init as the Build command
  4. Choose the Washington, D.C region was
  5. 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
  6. Name your service, for instance, express-mongodb
  7. 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

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": "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 \ --git-branch main \ --git-build-command "npm run mongodb:init" \ --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 [""] 24 Jan 23 10:06 UTC

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:

  • 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