MERN_MongoDB: 2.2 MongoDB installation and configuration - macOS

MERN/Topic/Backend/MongoDB/2.2_MongoDB_Installation_and_Configuration_MacOS.md

@@ -0,0 +1,236 @@
+# Installing MongoDB on macOS
+
+A step by step guide for installing MongoDB on macOS.
+
+### In macOs MongoDB Community Edition can be installed in two ways:
+- Using third party [Homebrew]('https://brew.sh/') package manager
+- Using .tgz Tarball
+
+## 1. Installing using third party package manager
+- Starting with MongoDB 4.4.1, installing MongoDB via Homebrew also installs the MongoDB Database Tools. See [MongoDB Database Tools]('https://docs.mongodb.com/database-tools/') for more information.
+- MongoDB 5.0 Community Edition supports macOS 10.14 or later.
+- See [Supported Platforms]('https://docs.mongodb.com/manual/administration/production-notes/#std-label-prod-notes-supported-platforms') for more information.
+
+### Pre-requisites
+  Ensure your system meets each of the following prerequisites. You only need to perform each prerequisite step once on your system. If you have already performed the prerequisite steps as part of an earlier MongoDB installation using Homebrew, you can skip to the installation procedure.
+
+  - **Install Xcode Command-Line Tools**
+
+      - Homebrew requires the Xcode command-line tools from Apple's Xcode.
+
+      - Install the Xcode command-line tools by running the following command in your macOS Terminal:
+      ```
+       xcode-select --install
+
+      ```
+   - **Install Homebrew**
+
+      - macOS does not include the Homebrew brew package by default.
+
+      - Install brew using the official [Homebrew installation instructions.]('https://brew.sh/#install')
+
+### Installing MongoDB 5.0 Community Edition
+
+  Follow these steps to install MongoDB Community Edition using Homebrew's brew package manager. Be sure that you have followed the installation prerequisites above before proceeding.
+
+  - Tap the [MongoDB Homebrew Tap]('https://github.com/mongodb/homebrew-brew') to download the official Homebrew formula for MongoDB and the Database Tools, by running the following command in your macOS Terminal:
+    ```
+    brew tap mongodb/brew
+    ```
+  - To install MongoDB, run the following command in your macOS Terminal application:
+    ```
+    brew install [email protected]
+    ```
+  - If you have previously installed an older version of the formula, you may encounter a ChecksumMismatchError. To resolve, see [Troubleshooting ChecksumMismatchError.]('https://docs.mongodb.com/manual/tutorial/install-mongodb-on-os-x/#std-label-troubleshooting-checksumerror')
+  - The installation includes the following binaries:
+
+    - The mongod server
+    - The mongos sharded cluster query router
+    - The MongoDB Shell, mongosh
+
+    In addition, the installation creates the following files and directories at the location specified below, depending on your Apple hardware:
+    |           | Intel Processor     | Apple M1 Processor                |
+    | :-------- | :------- | :------------------------- |
+    | Configuration file | `/usr/local/etc/mongod.conf` | `/opt/homebrew/etc/mongod.conf` |
+    | Log directory | `/usr/local/var/log/mongodb` | `/opt/homebrew/var/log/mongodb` |
+    | Data directory | `/usr/local/var/mongodb` | `/opt/homebrew/var/mongodb` |
+
+  See [Apple's documentation]('https://support.apple.com/en-us/HT211814') for the current list of Apple hardware using the M1 processor. You can also run the following command to check where brew has installed these files and directories:
+  ```
+  brew --prefix
+  ```
+  Starting with MongoDB 4.4.1, installing MongoDB via Homebrew also installs the MongoDB Database Tools.
+
+  ### Run MongoDB Community Edition
+
+  Follow these steps to run MongoDB Community Edition. These instructions assume that you are using the default settings.
+
+  You can run MongoDB as a macOS service using brew, or you can run MongoDB manually as a background process. It is recommended to run MongoDB as a macOS service, as doing so sets the correct system ulimit values automatically.
+
+  - To run MongoDB (i.e. the mongod process) **as a macOS service**, run:
+      ```
+      brew services start [email protected]
+      ```
+      To stop a mongod running as a macOS service, use the following command as needed:
+      ```
+      brew services stop [email protected]
+      ```
+  - To run MongoDB (i.e. the mongod process) manually **as a background process**, run:
+      - For macOS running Intel processors:
+        ```
+        mongod --config /usr/local/etc/mongod.conf --fork
+        ```
+      - For macOS running on Apple M1 processors:
+        ```
+        mongod --config /opt/homebrew/etc/mongod.conf --fork
+        ```
+  To stop a mongod running as a background process, connect to the mongod using mongosh, and issue the shutdown command as needed.
+
+  Both methods use the mongod.conf file created during the install. You can add your own MongoDB configuration options to this file as well.
+
+  **NOTE:**
+  ```
+  macOS may prevent mongod from running after installation. If you receive a security error when starting mongod indicating that the developer could not be identified or verified, do the following to grant mongod access to run:
+
+  - Open System Preferences
+
+  - Select the Security and Privacy pane.
+
+  - Under the General tab, click the button to the right of the message about mongod, labelled either Open Anyway or Allow Anyway depending on your version of macOS.
+  ```
+  To verify that MongoDB is running, perform one of the following:
+
+  - If you started MongoDB **as a macOS service**:
+    ```
+    brew services list
+    ```
+    You should see the service mongodb-community listed as started.
+  - If you started MongoDB manually **as a background process**:
+      ```
+      ps aux | grep -v grep | grep mongod
+      ```
+      You should see your mongod process in the output.
+
+  #### Connect and Use MongoDB
+
+  To begin using MongoDB, connect mongosh to the running instance. From a new terminal, issue the following:
+
+  ```
+  mongosh
+  ```
+  **NOTE:**
+  ```
+  macOS may prevent mongosh from running after installation. If you receive a security error when starting mongosh indicating that the developer could not be identified or verified, do the following to grant mongosh access to run:
+
+  - Open System Preferences
+  - Select the Security and Privacy pane.
+  - Under the General tab, click the button to the right of the message about mongosh, labelled either Open Anyway or Allow Anyway depending on your version of macOS.
+  ```
+
+  Once you have installed the MongoDB Server in the steps above, the Database Tools are available directly from the command line in your macOS Terminal application. For example you could run mongotop against your running MongoDB instance by invoking it in your macOS Terminal like so:
+  ```
+  mongotop
+  ```
+  It should start up, connect to your running mongod, and start reporting usage statistics.
+  ## 2. Installing using .tgz Tarball
+While MongoDB can be installed manually via a downloaded .tgz tarball as described in this document, it is recommended to use the brew package manager on your system to install MongoDB if possible. Using a package manager automatically installs all needed dependencies, provides an example mongod.conf file to get you started, and simplifies future upgrade and maintenance tasks.
+
+  ### Considerations
+  - **MongoDB Shell, mongosh**
+
+    When you use the .tgz package to install the server, you need to follow the [mongosh installation instructions]('https://docs.mongodb.com/mongodb-shell/install/') to download and install mongosh separately.
+
+  - **Platform Support**
+
+    MongoDB 5.0 Community Edition supports macOS 10.14 or later.
+
+  ### Install MongoDB Community Edition
+
+  Follow these steps to manually install MongoDB Community Edition from the .tgz.
+
+  #### 1. Download the tarball
+
+  Download the MongoDB Community tgz tarball from the following link: [MongoDB Download Center]('https://www.mongodb.com/try/download/community?tck=docs_server')
+
+    - In the Version dropdown, select the version of MongoDB to download.
+    - In the Platform dropdown, select macOS.
+    - In the Package dropdown, select tgz.
+    - Click Download.
+
+  #### 2. Extract the files from the downloaded archive
+
+  ```
+  tar -zxvf mongodb-macos-x86_64-5.0.tgz
+  ```
+  If your web browser automatically unzips the file as part of the download, the file would end in .tar instead.
+
+  #### 3. Ensure the binaries are in a directory listed in your PATH environment variable.
+
+  The MongoDB binaries are in the bin/ directory of the tarball. You can either:
+
+  - Copy the binaries into a directory listed in your ```PATH``` variable, such as ```/usr/local/bin``` (Update ```/path/to/the/mongodb-directory/``` with your installation directory as appropriate)
+
+  ```
+  sudo cp /path/to/the/mongodb-directory/bin/* /usr/local/bin/
+  ```
+
+  - Create symbolic links to the binaries from a directory listed in your ```PATH``` variable, such as ```/usr/local/bin``` (Update ```/path/to/the/mongodb-directory/``` with your installation directory as appropriate):
+  ```
+  sudo ln -s  /path/to/the/mongodb-directory/bin/* /usr/local/bin/
+  ```
+
+  ### Run MongoDB Community Edition
+
+  #### Procedure:
+
+  Follow these steps to run MongoDB Community Edition. These instructions assume that you are using the default settings.
+
+  #### 1. Create the data directory.
+
+  Before you start MongoDB for the first time, you must create the directory to which the mongod process will write data.
+
+  For example, to create the ```/usr/local/var/mongodb``` directory:
+  ```
+  sudo mkdir -p /usr/local/var/mongodb
+  ```
+  #### 2. Create the log directory.
+  You must also create the directory in which the ```mongod```` process will write its log file:
+
+  For example, to create the ```/usr/local/var/log/mongodb``` directory:
+  ```
+  sudo mkdir -p /usr/local/var/log/mongodb
+  ```
+
+  #### 3. Set permissions for the data and log directories.
+  Ensure that the user account running mongod has read and write permissions for these two directories. If you are running mongod as your own user account, and you just created the two directories above, they should already accessible to your user. Otherwise, you can use chown to set ownership, substituting the appropriate user:
+  ```
+  sudo chown my_mongodb_user /usr/local/var/mongodb
+  sudo chown my_mongodb_user /usr/local/var/log/mongodb
+  ```
+  #### 4. Run MongoDB.
+  To run MongoDB, run the mongod process at the system prompt, providing the two parameters ```dbpath``` and ```logpath``` from above, and the ```fork``` parameter to run mongod in the background. Alternatively, you may choose to store the values for ```dbpath```, ```logpath```, ```fork```, and many other parameters in a [configuration file.]('https://docs.mongodb.com/manual/reference/configuration-options/')
+
+  **Run ```mongod``` with command-line parameters**
+
+  Run the ```mongod``` process at the system prompt, providing the three necessary parameters directly on the command-line:
+
+  ```
+  mongod --dbpath /usr/local/var/mongodb --logpath /usr/local/var/log/mongodb/mongo.log --fork
+  ```
+  Run the ```mongod``` process at the system prompt, providing the path to a configuration file with the config parameter:
+  ```
+  mongod --config /usr/local/etc/mongod.conf
+  ```
+
+  #### 5. Verify that MongoDB has started successfully.
+  Verify that MongoDB has started successfully:
+  ```
+  ps aux | grep -v grep | grep mongod
+  ```
+  If you do not see a ```mongod``` process running, check the logfile for any error messages.
+
+  #### 6. Begin using MongoDB.
+  Start a ```mongosh``` session on the same host machine as the ```mongod```. You can run ```mongosh``` without any command-line options to connect to a ```mongod``` that is running on your localhost with the default port of 27017:
+  ```
+  mongosh
+  ```