# MongoDB Installation

✋ CAUTION

Starting from the release of Strapi v4, MongoDB is not supported natively anymore and no connector is available. For more information, please refer to the official communication on the topic (opens new window).

# Install MongoDB locally

# 1. Install MongoDB on your development environment

If you already have MongoDB installed locally and running as a background service, you may skip to Install Strapi locally with MongoDB. (If you have additional questions, please see the official MongoDB documentation (opens new window). )

Please complete the installation steps appropriate to your operating system.

# 2. Install Strapi locally with MongoDB

Follow these steps to create a Strapi project locally using the MongoDB database.

💡 TIP

MongoDB must already be running in the background.

  1. Create a new Strapi project

Path: ./

  • Use your down arrow key and select Custom (manual settings) and press enter:
? Choose your installation type
  Quickstart (recommended)
❯ Custom (manual settings)
  • Select MongoDB and press enter:
? Choose your installation type Custom (manual settings)
? Choose your main database:
  SQLite
❯ MongoDB
  MySQL
  Postgres
  • Press enter to select the remaining default options. It will look something like this:

? Choose your installation type Custom (manual settings)
? Choose your main database: MongoDB
? Database name: my-project
? Host: 127.0.0.1
? +srv connection: false
? Port (It will be ignored if you enable +srv): 27017
? Username:
? Password:
? Authentication database (Maybe "admin" or blank):
? Enable SSL connection: false

⏳ Testing database connection...
The app has been connected to the database successfully!

🏗  Application generation:
✔ Copy dashboard
✔ Installed dependencies.

👌 Your new application my-project is ready at /Users/david/Desktop/Projects/my-project.

⚡️ Change directory:
$ cd my-project

⚡️ Start application:
$ strapi develop

You have successfully installed Strapi with MongoDB on your local development environment. You are now ready to create your first user.

# Install on Atlas: MongoDB Atlas

Follow these steps to configure a local Strapi project to use a MongoDB Atlas (opens new window) free 512 MB account in production. (Please see MongoDB Atlas Documentation (opens new window) if you have any questions.)

# 1. Log in to your account to create a Project and a Cluster

  • First you need to Create a new Project.
  • Then click Build a Cluster, from the options page:
    • Choose AWS as your Cloud Provider & Region.
    • Select a Region. (Note: some Regions do not have a free tier.)
    • In Cluster Tier, select Shared Sandbox, Tier MO.
    • In Cluster Name, name your cluster.
  • Click the green Create Cluster button. You will get a message that says, "Your cluster is being created..."

# 2. Next, click on the Database Access in the left menu (under Security):

  • Click the green + ADD NEW USER button:
    • Enter a username.
    • Enter a password.
    • Under User Privileges ensure Read and write to any database is selected. Then click Add User to save.

# 3. Then whitelist your IP address. Click into Network Access, under Security in the left menu:

  • Click the green + ADD IP ADDRESS

    • Click ADD CURRENT IP ADDRESS or manually enter in an IP address to whitelist.
    • Leave a comment to label this IP Address. E.g. Office.
    • Then click the green Confirm button.
    • Delete the 0.0.0.0/0 configuration after testing the connection.

    💡 TIP

    If for any reason you need to test the configuration or other aspect of your connection to the database, you may want to set back the Allow Access from Anywhere. Follow this steps:

    • Click the green + ADD IP ADDRESS
      • Next add 0.0.0.0/0 in the Whitelist Entry. Note: In permanent projects you would configure this with the appropriate IP addresses.
      • Leave a comment to label this IP Address. E.g. Anywhere.
      • Click Confirm. Then wait until the status turns from Pending to Active.

    💡 TIP

    If you are serving you Strapi project from a known IP Address then follow the following steps to allow Network Access.

    • Manually enter in an IP address to whitelist, for your Strapi server.
    • Leave a comment to label this IP Address. E.g. Heroku Server
    • Then click the green Confirm button.

# 4. Retrieve database credentials

MongoDB Atlas automatically exposes the database credentials into a single environment variable accessible by your app. To locate it, follow these steps:

  • Under Atlas in the left-hand, click on Clusters. This should take you to your cluster. Next, click CONNECT and then Connect Your Application.
  • Under 1. Choose your driver version, select DRIVER as Node.js and VERSION as 3.6 or later.

    ✋ CAUTION

    You must use Version: 3.6 or later.

  • This should show a Connection String Only similar to this:

mongodb+srv://username:<password>@cluster0.blah.mongodb.net/myFirstDatabase?retryWrites=true&w=majority

✋ CAUTION

Please note the <password> after your username. In this example, after mongodb+srv://username:. You will need to replace the <password> with the password you created earlier for this user in your MongoDB Atlas account.

# 5. Update and replace your existing /database.js config file for the appropriate environment (development | production).

Replace the contents of /database.js with the following and replace < password > with the password of the user of your database you created earlier:

Path: ./config/database.js.

️❗️ WARNING

We recommend replacing sensitive (eg. "URI string" above) information in your database configuration files before uploading your project to a public repository such as GitHub. For more information about using environment variables, please read configurations.

You are now ready use Strapi locally or to deploy your project to an external hosting provider and use MongoDB Atlas as your database server.