Set up MongoDB

You need one MongoDB database. Choose Option A to run it on your own computer or server, or Option B for a free cloud database from MongoDB Atlas. Atlas is the easiest choice if you have never installed MongoDB.

Option A: install MongoDB on your computer

macOS (with Homebrew)

brew tap mongodb/brew
brew install mongodb-community
brew services start mongodb-community

Windows

1. Download MongoDB Community Server (the .msi file) from mongodb.com/try/download/community.
2. Run it. Choose Complete, and keep Install MongoD as a Service turned on. MongoDB then starts by itself with Windows.
3. Optional: install MongoDB Shell (mongosh) from mongodb.com/try/download/shell to test the connection.

Ubuntu 24.04 (with apt)

sudo apt-get install -y gnupg curl
curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc | \
  sudo gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg --dearmor
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/ubuntu noble/mongodb-org/8.0 multiverse" | \
  sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list
sudo apt-get update
sudo apt-get install -y mongodb-org
sudo systemctl enable --now mongod

For other Ubuntu or Debian versions, the repository line is a little different. Follow the official guide at mongodb.com/docs/manual/administration/install-on-linux.

Docker (any system)

docker run -d -p 27017:27017 --name mongo mongo:7

To keep your data when the container is removed, add a volume: docker run -d -p 27017:27017 -v chatcart-db:/data/db --name mongo mongo:7.

Check that MongoDB is running

mongosh --eval "db.runCommand({ ping: 1 })"

# with Docker:
docker exec -it mongo mongosh --eval "db.runCommand({ ping: 1 })"

You should see { ok: 1 }. If you see ECONNREFUSED, MongoDB is not running. Start it with brew services start mongodb-community (macOS), sudo systemctl start mongod (Linux), the Services app (Windows, service "MongoDB"), or docker start mongo.

Your connection string

MONGODB_URI=mongodb://127.0.0.1:27017/chatcart

127.0.0.1:27017 is the address and port of MongoDB. chatcart at the end is the database name. MongoDB creates it the first time ChatCart writes to it. Use 127.0.0.1, not localhost: on new Node.js versions, localhost can point to the IPv6 address ::1, where MongoDB often does not listen.

Option B: free MongoDB Atlas cluster

Atlas is MongoDB in the cloud. The free tier is enough to try ChatCart and to run a small shop. The Atlas screens change from time to time, so a button name can be a little different from what you read here.

1. Create an account at mongodb.com/cloud/atlas/register and sign in.
2. Create a free cluster. Click Create (or Build a Database), choose the Free tier, pick a region near your customers, and click Create Deployment.
3. Create a database user. Atlas asks for a username and password. Write them down. Tip: click Autogenerate Secure Password. It makes a password with only letters and numbers, which avoids problems in step 7.
4. Allow your IP address. In the left menu open Network Access (under Security), then Add IP Address. Click Add Current IP Address for your own computer. For your server, add the server's IP address.
5. Connect. Go back to Clusters (or Database), click Connect on your cluster, and choose Drivers.
6. Copy the connection string. It looks like this:

   mongodb+srv://shopuser:<db_password>@cluster0.abcde.mongodb.net/?retryWrites=true&w=majority&appName=Cluster0

7. Put in your password. Replace <db_password> (in older screens <password>) with the password of the database user, without the < > signs.
8. Add the database name. Type chatcart after the / and before the ?. If you skip this, the data goes into a database named test.

   mongodb+srv://shopuser:[email protected]/chatcart?retryWrites=true&w=majority&appName=Cluster0

9. Paste it into .env.local as the value of MONGODB_URI.

Special characters in the password

The password is part of a web address, so some characters must be written in a coded form ("URL-encoded"). Replace them like this:

For example, the password p@ss#1 becomes p%40ss%231. Node.js can do it for you: node -e "console.log(encodeURIComponent('p@ss#1'))". Easier still: give the database user a password with only letters and numbers.