MongoDB 로컬 설치 가이드 - 개발 환경 구축하기

MongoDB를 처음 설치하려고 공식 문서를 열었는데, 어디서부터 시작해야 할지 막막했던 적 있나요?

저도 처음 MongoDB를 설치할 때 같은 경험을 했습니다. “Community Edition과 Enterprise는 뭐가 다르지?”, “Homebrew로 할까, Docker로 할까?”, “설치는 됐는데 왜 연결이 안 되지?” 하면서 몇 시간을 헤맸던 기억이 있습니다.

이 문서에서는 MongoDB를 로컬 환경에 설치하는 가장 확실한 방법을 정리했습니다. 단순히 “이 명령어를 치세요”가 아니라, 왜 이 방법을 선택해야 하는지, 어떤 함정이 있는지까지 함께 다룹니다.

왜 MongoDB를 로컬에 설치할까?

“MongoDB Atlas 같은 클라우드 서비스가 있는데 왜 로컬에 설치해야 하나요?”

좋은 질문입니다. 클라우드 서비스는 편리하지만, 로컬 설치가 필요한 상황이 분명히 있습니다:

로컬 설치가 필요한 경우:

┌─────────────────────────────────────────────────────────────────┐
│  1. 오프라인 개발                                                │
│     └─ 비행기, 카페(와이파이 불안정), 보안 네트워크 환경           │
│                                                                  │
│  2. 빠른 개발 사이클                                             │
│     └─ 네트워크 지연 없이 밀리초 단위 응답                        │
│                                                                  │
│  3. 데이터 프라이버시                                            │
│     └─ 민감한 테스트 데이터를 클라우드에 올리고 싶지 않을 때       │
│                                                                  │
│  4. 비용 절감                                                    │
│     └─ 학습/개발 단계에서 무료로 무제한 사용                      │
│                                                                  │
│  5. 완전한 제어                                                  │
│     └─ 설정, 버전, 플러그인을 자유롭게 조절                       │
└─────────────────────────────────────────────────────────────────┘

핵심 포인트: 개발 환경에서는 로컬 MongoDB, 프로덕션에서는 Atlas나 자체 클러스터를 사용하는 것이 일반적인 패턴입니다.

설치 전 알아두기

MongoDB를 설치하기 전에, 몇 가지 결정을 내려야 합니다. 이 섹션에서는 “어떤 버전을 선택할지”, “어떤 방법으로 설치할지”에 대한 기준을 제시합니다.

MongoDB 버전, 뭘 선택해야 할까?

MongoDB에는 두 가지 에디션이 있습니다:

┌────────────────────────────────────────────────────────────────────┐
│  MongoDB Community Edition (무료)                                  │
│  ────────────────────────────────────────────────────────────────  │
│  ✅ 개발/학습용으로 충분                                           │
│  ✅ CRUD, 인덱싱, 집계 등 핵심 기능 모두 포함                       │
│  ✅ 상업적 사용 가능 (SSPL 라이선스)                               │
│  ✅ 대부분의 스타트업/중소기업에서 사용                            │
└────────────────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────────────┐
│  MongoDB Enterprise Edition (유료)                                 │
│  ────────────────────────────────────────────────────────────────  │
│  ✅ LDAP/Kerberos 인증                                             │
│  ✅ 암호화 (저장 데이터 암호화)                                     │
│  ✅ 감사 로깅                                                      │
│  ✅ 24/7 기술 지원                                                 │
│  → 대기업, 금융권, 의료 분야에서 주로 사용                          │
└────────────────────────────────────────────────────────────────────┘

결론: 학습이나 일반 개발 목적이라면 Community Edition으로 충분합니다. 이 문서에서도 Community Edition을 기준으로 설명합니다.

시스템 요구사항

MongoDB를 설치하기 전에 내 컴퓨터가 요구사항을 충족하는지 확인하세요:

최소 사양:
────────────────────────────────────────
RAM         │  4GB 이상 (8GB 권장)
Disk        │  10GB 이상 여유 공간
CPU         │  x86_64 또는 ARM64
────────────────────────────────────────

지원 OS:
────────────────────────────────────────
macOS       │  10.14 (Mojave) 이상
            │  Intel 또는 Apple Silicon 모두 지원
────────────────────────────────────────
Windows     │  Windows 10/11 (64-bit)
            │  Windows Server 2016 이상
────────────────────────────────────────
Linux       │  Ubuntu 20.04/22.04 LTS
            │  RHEL/CentOS 8/9
            │  Debian 11/12
────────────────────────────────────────

설치 방법, 어떤 걸 선택할까?

설치 방법은 여러 가지가 있는데, 상황에 따라 최선의 선택이 다릅니다:

방법	장점	단점	이런 분께 추천
Homebrew	한 줄로 설치, 업데이트 쉬움	macOS 전용	macOS 개발자
공식 패키지	가장 안정적, 공식 지원	수동 업데이트 필요	안정성 중시
Docker	환경 격리, 버전 관리 쉬움	Docker 학습 필요	여러 버전 테스트, 팀 환경 통일
Atlas (Cloud)	설치 불필요, 관리 편함	인터넷 필요, 무료 제한	프로덕션, 빠른 시작

저의 추천:

macOS 사용자 → Homebrew (가장 간편)
팀 프로젝트 → Docker (환경 통일)
Windows 사용자 → MSI 설치 파일 (가장 안정적)

macOS에 설치하기

macOS에서 MongoDB를 설치하는 방법은 크게 두 가지입니다. Homebrew를 사용하면 정말 간단하게 설치할 수 있어서, 대부분의 경우 Homebrew를 추천합니다.

방법 1: Homebrew 사용 (강력 추천)

Homebrew는 macOS의 패키지 관리자입니다. 이미 사용하고 계시다면 MongoDB 설치는 정말 간단합니다.

설치 과정:

# 1. Homebrew가 설치되어 있는지 확인
brew --version
# 출력 예: Homebrew 4.x.x

# Homebrew가 없다면 먼저 설치 (https://brew.sh)
# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 2. MongoDB 탭(tap) 추가
# MongoDB는 기본 Homebrew 저장소에 없어서 별도로 추가해야 합니다
brew tap mongodb/brew

# 3. MongoDB Community Edition 설치
brew install mongodb-community@8.0

# 4. 설치 확인
mongod --version
# 출력 예: db version v8.0.x

설치 완료 후 파일 위치:

설치된 위치 (Apple Silicon Mac 기준):
────────────────────────────────────────────────────────────
MongoDB 실행 파일  │  /opt/homebrew/bin/mongod
설정 파일          │  /opt/homebrew/etc/mongod.conf
데이터 디렉토리     │  /opt/homebrew/var/mongodb
로그 파일          │  /opt/homebrew/var/log/mongodb/mongo.log
────────────────────────────────────────────────────────────

Intel Mac의 경우 /opt/homebrew 대신 /usr/local 경로입니다.

MongoDB 시작하기:

# ✅ 권장: 백그라운드 서비스로 실행
# 컴퓨터 재시작해도 자동으로 실행됩니다
brew services start mongodb-community@8.0

# 서비스 상태 확인
brew services list | grep mongodb
# 출력 예: mongodb-community@8.0 started b ~/Library/LaunchAgents/...

# 서비스 중지
brew services stop mongodb-community@8.0

# 서비스 재시작
brew services restart mongodb-community@8.0

# 일회성 실행 (터미널 닫으면 종료)
# 디버깅이나 로그 확인이 필요할 때 유용합니다
mongod --config /opt/homebrew/etc/mongod.conf

연결 테스트:

# MongoDB Shell로 연결
mongosh

# 성공하면 이런 프롬프트가 나타납니다:
# test>

방법 2: 공식 패키지 다운로드

Homebrew 없이 설치하고 싶다면, 공식 패키지를 직접 다운로드할 수 있습니다.

# 1. 공식 사이트에서 다운로드
# https://www.mongodb.com/try/download/community
# Platform: macOS, Package: TGZ 선택

# 2. 다운로드한 파일 압축 해제
tar -zxvf mongodb-macos-arm64-8.0.0.tgz  # Apple Silicon
# 또는
tar -zxvf mongodb-macos-x86_64-8.0.0.tgz  # Intel Mac

# 3. 적절한 위치로 이동
sudo mv mongodb-macos-arm64-8.0.0 /usr/local/mongodb

# 4. PATH에 추가 (~/.zshrc 또는 ~/.bash_profile)
echo 'export PATH="/usr/local/mongodb/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 5. 데이터 및 로그 디렉토리 생성
sudo mkdir -p /usr/local/var/mongodb
sudo mkdir -p /usr/local/var/log/mongodb

# 현재 사용자에게 권한 부여
sudo chown -R $(whoami) /usr/local/var/mongodb
sudo chown -R $(whoami) /usr/local/var/log/mongodb

# 6. MongoDB 시작
mongod --dbpath /usr/local/var/mongodb \
       --logpath /usr/local/var/log/mongodb/mongo.log \
       --fork

💡 Tip: --fork 옵션은 MongoDB를 백그라운드에서 실행합니다. 로그는 지정한 파일에 기록됩니다.

Windows에 설치하기

Windows에서는 MSI 설치 파일을 사용하는 것이 가장 간편하고 안정적입니다. 설치 마법사가 대부분의 설정을 자동으로 처리해줍니다.

방법 1: MSI 설치 파일 (강력 추천)

설치 과정:

1. 공식 다운로드 페이지 방문
   https://www.mongodb.com/try/download/community

2. 다음 옵션 선택:
   - Version: 8.0.x (Current)
   - Platform: Windows
   - Package: msi

3. 다운로드 후 설치 파일 실행

4. 설치 마법사에서 선택:
   ┌─────────────────────────────────────────────┐
   │  MongoDB Setup                              │
   ├─────────────────────────────────────────────┤
   │  ✅ Complete (전체 설치) 선택               │
   │                                             │
   │  Service Configuration:                     │
   │  ✅ Install MongoDB as a Service            │
   │     → 컴퓨터 시작 시 자동 실행              │
   │  ✅ Run service as Network Service user     │
   │                                             │
   │  ✅ Install MongoDB Compass                 │
   │     → GUI 도구, 초보자에게 매우 유용        │
   └─────────────────────────────────────────────┘

5. Install 클릭 → 완료!

설치 완료 후 파일 위치:

Windows 기본 설치 경로:
────────────────────────────────────────────────────────────
MongoDB 실행 파일  │  C:\Program Files\MongoDB\Server\8.0\bin\mongod.exe
설정 파일          │  C:\Program Files\MongoDB\Server\8.0\bin\mongod.cfg
데이터 디렉토리     │  C:\Program Files\MongoDB\Server\8.0\data
로그 파일          │  C:\Program Files\MongoDB\Server\8.0\log\mongod.log
────────────────────────────────────────────────────────────

서비스 관리 (PowerShell 관리자 권한):

# 서비스 상태 확인
Get-Service MongoDB

# 서비스 시작
Start-Service MongoDB
# 또는: net start MongoDB

# 서비스 중지
Stop-Service MongoDB
# 또는: net stop MongoDB

# 서비스 재시작
Restart-Service MongoDB

PATH 환경변수 추가 (선택사항):

터미널 어디서든 mongosh 명령어를 사용하려면 PATH에 추가해야 합니다:

Windows 검색에서 "환경 변수" 검색
"시스템 환경 변수 편집" 클릭
"환경 변수" 버튼 클릭
"시스템 변수"에서 "Path" 선택 → "편집"
"새로 만들기" → 경로 추가:
   C:\Program Files\MongoDB\Server\8.0\bin
확인 → 터미널 재시작

연결 테스트:

# MongoDB Shell 실행
mongosh

# 성공하면:
# Current Mongosh Log ID: ...
# Connecting to: mongodb://127.0.0.1:27017/...
# test>

방법 2: Chocolatey (패키지 관리자)

Windows에서도 패키지 관리자를 사용하고 싶다면 Chocolatey가 있습니다:

# PowerShell (관리자 권한)

# Chocolatey가 없다면 먼저 설치
# https://chocolatey.org/install

# MongoDB 설치
choco install mongodb

# 서비스 시작
net start MongoDB

Linux에 설치하기

Linux에서는 배포판별로 패키지 관리자가 다르므로, 각각의 방법을 설명합니다. 패키지 관리자를 통해 설치하면 의존성 관리와 업데이트가 편리합니다.

Ubuntu/Debian

Ubuntu는 가장 많이 사용되는 Linux 배포판 중 하나입니다. APT 패키지 관리자를 통해 설치합니다.

# 1. MongoDB 공개 GPG 키 가져오기
# 패키지의 무결성을 검증하는 데 필요합니다
curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc | \
   sudo gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg --dearmor

# 2. MongoDB 저장소 추가
# Ubuntu 22.04 (Jammy) 기준입니다. 다른 버전은 공식 문서 참조.
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] \
https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/8.0 multiverse" | \
   sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list

# 3. 패키지 목록 업데이트
sudo apt-get update

# 4. MongoDB 설치
sudo apt-get install -y mongodb-org

# 5. MongoDB 서비스 시작
sudo systemctl start mongod

# 6. 부팅 시 자동 시작 설정
sudo systemctl enable mongod

# 7. 상태 확인
sudo systemctl status mongod
# Active: active (running) 이면 성공!

설치 완료 후 파일 위치:

Linux 기본 설치 경로:
────────────────────────────────────────────────────────────
MongoDB 실행 파일  │  /usr/bin/mongod
설정 파일          │  /etc/mongod.conf
데이터 디렉토리     │  /var/lib/mongodb
로그 파일          │  /var/log/mongodb/mongod.log
────────────────────────────────────────────────────────────

서비스 관리:

# 시작
sudo systemctl start mongod

# 중지
sudo systemctl stop mongod

# 재시작
sudo systemctl restart mongod

# 상태 확인
sudo systemctl status mongod

# 실시간 로그 확인 (문제 해결 시 유용)
sudo tail -f /var/log/mongodb/mongod.log

RHEL/CentOS/Fedora

Red Hat 계열 배포판에서는 YUM/DNF 패키지 관리자를 사용합니다:

# 1. MongoDB 저장소 파일 생성
sudo tee /etc/yum.repos.d/mongodb-org-8.0.repo << 'EOF'
[mongodb-org-8.0]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/8/mongodb-org/8.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server-8.0.asc
EOF

# 2. MongoDB 설치
sudo yum install -y mongodb-org
# 또는 Fedora/RHEL 8+:
# sudo dnf install -y mongodb-org

# 3. 서비스 시작 및 자동 시작 설정
sudo systemctl start mongod
sudo systemctl enable mongod

# 4. 상태 확인
sudo systemctl status mongod

Docker로 설치하기

Docker는 MongoDB를 격리된 환경에서 실행할 수 있게 해줍니다. 특히 팀 프로젝트에서 “내 컴퓨터에선 되는데…“라는 문제를 피할 수 있어서 많이 사용됩니다.

왜 Docker로 설치할까?

Docker의 장점:
────────────────────────────────────────────────────────────
1. 환경 격리      │  호스트 시스템을 깨끗하게 유지
2. 버전 관리      │  여러 MongoDB 버전을 쉽게 테스트
3. 재현성        │  팀원 모두 동일한 환경 보장
4. 삭제 용이      │  docker rm 한 번으로 깔끔하게 제거
5. 설정 코드화    │  docker-compose.yml로 설정 버전 관리
────────────────────────────────────────────────────────────

방법 1: Docker 명령어로 실행

가장 빠르게 MongoDB를 실행하는 방법입니다:

# MongoDB 컨테이너 실행
docker run -d \
  --name mongodb \
  -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=password123 \
  -v mongodb_data:/data/db \
  mongo:8.0

# 실행 확인
docker ps | grep mongodb

# MongoDB Shell로 접속
docker exec -it mongodb mongosh -u admin -p password123

명령어 옵션 설명:

옵션 설명:
────────────────────────────────────────────────────────────
-d                           │  백그라운드 실행 (detached)
--name mongodb               │  컨테이너 이름 지정
-p 27017:27017              │  포트 매핑 (호스트:컨테이너)
-e MONGO_INITDB_...         │  환경 변수 (초기 관리자 계정)
-v mongodb_data:/data/db    │  볼륨 마운트 (데이터 영구 저장)
mongo:8.0                    │  사용할 이미지와 버전
────────────────────────────────────────────────────────────

컨테이너 관리:

# 컨테이너 중지
docker stop mongodb

# 컨테이너 시작
docker start mongodb

# 컨테이너 재시작
docker restart mongodb

# 로그 확인
docker logs mongodb
docker logs -f mongodb  # 실시간 로그

# 컨테이너 삭제 (데이터는 볼륨에 유지)
docker rm mongodb

# 완전 삭제 (볼륨 포함)
docker rm mongodb
docker volume rm mongodb_data

방법 2: Docker Compose 사용 (강력 추천)

Docker Compose를 사용하면 설정을 파일로 관리할 수 있어서, 팀과 공유하기 좋습니다.

docker-compose.yml 파일 생성:

# docker-compose.yml
version: '3.8'

services:
  mongodb:
    image: mongo:8.0
    container_name: mongodb
    restart: unless-stopped
    ports:
      - "27017:27017"
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password123
    volumes:
      - mongodb_data:/data/db
      - mongodb_config:/data/configdb
    networks:
      - mongodb_network

  # MongoDB GUI 도구 (선택사항)
  # 브라우저에서 http://localhost:8081 로 접속
  mongo-express:
    image: mongo-express:latest
    container_name: mongo-express
    restart: unless-stopped
    ports:
      - "8081:8081"
    environment:
      ME_CONFIG_MONGODB_ADMINUSERNAME: admin
      ME_CONFIG_MONGODB_ADMINPASSWORD: password123
      ME_CONFIG_MONGODB_URL: mongodb://admin:password123@mongodb:27017/
      ME_CONFIG_BASICAUTH: "false"
    depends_on:
      - mongodb
    networks:
      - mongodb_network

volumes:
  mongodb_data:
  mongodb_config:

networks:
  mongodb_network:
    driver: bridge

Docker Compose 명령어:

# 컨테이너 시작 (백그라운드)
docker-compose up -d

# 상태 확인
docker-compose ps

# 로그 확인
docker-compose logs mongodb
docker-compose logs -f  # 실시간 로그

# 컨테이너 중지
docker-compose down

# 완전 삭제 (볼륨 포함) - 주의: 모든 데이터 삭제!
docker-compose down -v

접속 정보:

Docker 환경 접속 정보:
────────────────────────────────────────────────────────────
MongoDB         │  localhost:27017
Username        │  admin
Password        │  password123
────────────────────────────────────────────────────────────
Mongo Express   │  http://localhost:8081
(웹 GUI)        │  인증 없이 접속 가능 (개발용)
────────────────────────────────────────────────────────────

⚠️ 보안 주의: 위 비밀번호는 예시입니다. 실제 프로젝트에서는 반드시 강력한 비밀번호를 사용하고, .env 파일로 관리하세요.

설치 확인 및 기본 사용법

설치가 완료되었다면, 제대로 동작하는지 확인해봐야겠죠? 이 섹션에서는 설치 확인 방법과 MongoDB의 기본 사용법을 다룹니다.

설치 확인

# 1. MongoDB 서버 버전 확인
mongod --version
# 출력 예:
# db version v8.0.0
# Build Info: {
#     "version": "8.0.0",
#     ...
# }

# 2. MongoDB Shell 버전 확인
mongosh --version
# 출력 예: 2.x.x

# 3. 서버 연결 테스트
mongosh
# 성공하면:
# Current Mongosh Log ID: ...
# Connecting to: mongodb://127.0.0.1:27017/...
# Using MongoDB: 8.0.0
# test>

연결 성공/실패 확인

// MongoDB Shell에서 실행

// ✅ 연결 성공 확인
test> db.version()
"8.0.0"

test> db.runCommand({ ping: 1 })
{ ok: 1 }

// ❌ 연결 실패 시 이런 에러가 나타납니다:
// MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017
// → MongoDB 서버가 실행되지 않았다는 의미입니다

MongoDB Shell 기본 명령어

처음 MongoDB를 사용한다면, 이 기본 명령어들을 알아두면 좋습니다:

// MongoDB Shell (mongosh)에서 실행

// ────────────────────────────────────────
// 데이터베이스 관련
// ────────────────────────────────────────

// 현재 데이터베이스 확인
db
// 출력: test (기본 데이터베이스)

// 모든 데이터베이스 목록
show dbs
// 출력:
// admin   40.00 KiB
// config  60.00 KiB
// local   40.00 KiB

// 데이터베이스 선택 (없으면 생성)
use myapp
// 출력: switched to db myapp


// ────────────────────────────────────────
// 데이터 삽입/조회 (CRUD 기초)
// ────────────────────────────────────────

// 데이터 삽입
db.users.insertOne({
  name: "홍길동",
  email: "hong@example.com",
  age: 30
})
// 출력: { acknowledged: true, insertedId: ObjectId("...") }

// 모든 데이터 조회
db.users.find()
// 출력:
// [
//   {
//     _id: ObjectId("..."),
//     name: '홍길동',
//     email: 'hong@example.com',
//     age: 30
//   }
// ]

// 조건 조회
db.users.find({ age: { $gte: 25 } })

// 데이터 수정
db.users.updateOne(
  { name: "홍길동" },
  { $set: { age: 31 } }
)

// 데이터 삭제
db.users.deleteOne({ name: "홍길동" })


// ────────────────────────────────────────
// 서버 정보 확인
// ────────────────────────────────────────

// 서버 상태
db.serverStatus()

// 데이터베이스 통계
db.stats()

// 컬렉션 목록
show collections


// ────────────────────────────────────────
// 종료
// ────────────────────────────────────────
exit
// 또는 Ctrl+D

초기 설정 가이드

MongoDB를 설치했다면, 바로 개발에 사용할 수도 있지만, 몇 가지 초기 설정을 해두면 더 안전하고 편리하게 사용할 수 있습니다.

1. 보안 설정: 인증 활성화

기본적으로 MongoDB는 인증 없이 실행됩니다. 개발 환경에서는 편리하지만, 보안상 위험할 수 있습니다.

🚨 실제 사례: 2017년에 수만 개의 MongoDB 서버가 인증 없이 인터넷에 노출되어 해킹당한 사례가 있습니다. 개발 환경이라도 인증을 설정하는 습관을 들이는 것이 좋습니다.

관리자 계정 생성:

# MongoDB Shell 접속
mongosh

// admin 데이터베이스 선택
use admin

// 관리자 계정 생성
db.createUser({
  user: "admin",
  pwd: "여기에_강력한_비밀번호",  // 반드시 변경하세요!
  roles: [
    { role: "userAdminAnyDatabase", db: "admin" },
    { role: "readWriteAnyDatabase", db: "admin" }
  ]
})

// 생성 확인
db.getUsers()

// 종료
exit

설정 파일에서 인증 활성화:

# 설정 파일 경로:
# macOS (Homebrew): /opt/homebrew/etc/mongod.conf
# Linux: /etc/mongod.conf
# Windows: C:\Program Files\MongoDB\Server\8.0\bin\mongod.cfg

# 파일 편집 (macOS/Linux 예시)
sudo nano /opt/homebrew/etc/mongod.conf

# mongod.conf에 다음 내용 추가 (없다면)
security:
  authorization: enabled

MongoDB 재시작:

# macOS (Homebrew)
brew services restart mongodb-community@8.0

# Linux
sudo systemctl restart mongod

# Windows (관리자 권한 PowerShell)
Restart-Service MongoDB

인증하여 접속:

# 이제 인증 없이는 접속할 수 없습니다
mongosh  # ❌ 대부분의 명령어 실패

# 인증하여 접속
mongosh -u admin -p 여기에_강력한_비밀번호 --authenticationDatabase admin
# ✅ 정상 작동

2. 애플리케이션용 사용자 생성

관리자 계정으로 애플리케이션을 실행하는 것은 보안상 좋지 않습니다. 애플리케이션별로 별도의 사용자를 만들어 최소 권한만 부여하세요.

// 관리자로 로그인한 상태에서

// 애플리케이션용 데이터베이스 선택
use myapp

// 애플리케이션용 사용자 생성
db.createUser({
  user: "myapp_user",
  pwd: "myapp_password",  // 실제로는 강력한 비밀번호 사용
  roles: [
    { role: "readWrite", db: "myapp" }  // 이 DB에 대해서만 읽기/쓰기 권한
  ]
})

// 사용자 확인
db.getUsers()

3. 연결 문자열 (Connection String)

애플리케이션에서 MongoDB에 연결할 때는 연결 문자열을 사용합니다:

연결 문자열 형식:
mongodb://[username:password@]host[:port]/[database][?options]

예시:
────────────────────────────────────────────────────────────

1. 로컬, 인증 없음 (개발용):
   mongodb://localhost:27017/myapp

2. 로컬, 인증 있음:
   mongodb://myapp_user:myapp_password@localhost:27017/myapp

3. Docker 환경 (authSource 필요):
   mongodb://admin:password123@localhost:27017/myapp?authSource=admin

4. Replica Set:
   mongodb://user:pass@host1:27017,host2:27017,host3:27017/myapp?replicaSet=rs0

프로그래밍 언어별 연결 예시:

// Node.js (Mongoose)
const mongoose = require('mongoose');
await mongoose.connect('mongodb://localhost:27017/myapp');

# Python (PyMongo)
from pymongo import MongoClient
client = MongoClient('mongodb://localhost:27017/')
db = client['myapp']

// Java (MongoDB Driver)
MongoClient mongoClient = MongoClients.create("mongodb://localhost:27017");
MongoDatabase database = mongoClient.getDatabase("myapp");

4. 데이터베이스 백업 설정

데이터는 언제든 손실될 수 있습니다. 정기적인 백업은 필수입니다.

# 전체 백업
mongodump --out /backup/$(date +%Y%m%d)

# 특정 데이터베이스만 백업
mongodump --db myapp --out /backup/myapp

# 인증이 필요한 경우
mongodump \
  --username admin \
  --password 비밀번호 \
  --authenticationDatabase admin \
  --out /backup/$(date +%Y%m%d)

# 복원
mongorestore /backup/20251120/

# 특정 데이터베이스만 복원
mongorestore --db myapp /backup/20251120/myapp

자동 백업 스크립트 (Linux/macOS):

#!/bin/bash
# backup-mongodb.sh

BACKUP_DIR="/backup/mongodb"
DATE=$(date +%Y%m%d_%H%M%S)

# 백업 실행
mongodump --out "$BACKUP_DIR/$DATE"

# 7일 이전 백업 삭제 (디스크 용량 관리)
find $BACKUP_DIR -type d -mtime +7 -exec rm -rf {} \; 2>/dev/null

echo "Backup completed: $BACKUP_DIR/$DATE"

# crontab에 추가 (매일 새벽 2시 실행)
crontab -e
# 다음 줄 추가:
0 2 * * * /path/to/backup-mongodb.sh

함정과 해결책

MongoDB 설치 과정에서 자주 발생하는 문제들과 해결 방법을 정리했습니다. 에러 메시지가 나타났을 때 이 섹션을 참고하세요.

함정 1: “connect ECONNREFUSED” 에러

가장 흔한 에러입니다. MongoDB 서버에 연결할 수 없다는 의미입니다.

# ❌ 에러 메시지
MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017

원인과 해결:

# 1. MongoDB 서버가 실행 중인지 확인
# macOS
brew services list | grep mongodb

# Linux
sudo systemctl status mongod

# Windows
Get-Service MongoDB


# 2. 서버가 실행 중이 아니라면 시작
# macOS
brew services start mongodb-community@8.0

# Linux
sudo systemctl start mongod

# Windows
Start-Service MongoDB


# 3. 포트가 이미 사용 중인지 확인
lsof -i :27017        # macOS/Linux
netstat -an | findstr 27017  # Windows


# 4. 로그 확인으로 원인 파악
# macOS (Homebrew)
tail -50 /opt/homebrew/var/log/mongodb/mongo.log

# Linux
sudo tail -50 /var/log/mongodb/mongod.log

함정 2: “Data directory not found” 에러

MongoDB가 데이터를 저장할 디렉토리를 찾지 못하는 경우입니다.

# ❌ 에러 메시지
Data directory /data/db not found

해결:

# 1. 디렉토리 생성
sudo mkdir -p /data/db

# 2. 권한 설정
sudo chown -R $(whoami) /data/db

# 또는 다른 경로 지정하여 실행
mongod --dbpath /path/to/your/data

함정 3: “Address already in use” 에러

27017 포트를 다른 프로세스가 사용 중인 경우입니다.

# ❌ 에러 메시지
Address already in use for socket: 0.0.0.0:27017

해결:

# 1. 해당 포트를 사용 중인 프로세스 확인
lsof -i :27017  # macOS/Linux

# 출력 예:
# COMMAND   PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
# mongod   1234 user   10u  IPv4  ...

# 2. 기존 프로세스 종료
kill -9 1234  # PID로 종료

# 3. 또는 다른 포트로 실행
mongod --port 27018
mongosh --port 27018

함정 4: “Unauthorized” 에러

인증이 활성화된 상태에서 인증 없이 접속하려는 경우입니다.

// ❌ 에러 메시지
MongoServerError: command find requires authentication

해결:

# ✅ 인증 정보를 포함하여 접속
mongosh -u 사용자명 -p 비밀번호 --authenticationDatabase admin

# 또는 연결 문자열에 authSource 추가
mongosh "mongodb://user:pass@localhost:27017/myapp?authSource=admin"

함정 5: Permission Denied 에러

파일이나 디렉토리에 대한 권한이 없는 경우입니다.

# ❌ 에러 메시지
exception in initAndListen: NonExistentPath: Data directory /var/lib/mongodb not found
# 또는
permission denied

해결:

# 1. 디렉토리 소유권 확인
ls -la /var/lib/mongodb

# 2. 소유권 변경 (Linux)
sudo chown -R mongodb:mongodb /var/lib/mongodb

# macOS (Homebrew)
sudo chown -R $(whoami) /opt/homebrew/var/mongodb

# 3. 권한 설정
chmod -R 755 /var/lib/mongodb

함정 6: MongoDB Compass가 연결 안 됨

GUI 도구인 Compass에서 연결이 안 되는 경우입니다.

❌ 증상: "connection attempt failed" 또는 계속 로딩

체크리스트:

1. MongoDB 서버가 실행 중인지 확인
   → 터미널에서 mongosh로 먼저 테스트

2. 연결 문자열 확인
   → mongodb://localhost:27017 (기본)
   → mongodb://user:pass@localhost:27017/?authSource=admin (인증 시)

3. 방화벽 확인
   → macOS: 시스템 환경설정 → 보안 및 개인정보 보호 → 방화벽
   → Windows: Windows Defender 방화벽 → 앱 허용
   → Linux: sudo ufw status

4. 인증 정보 확인
   → Authentication을 "Username / Password"로 설정
   → Authentication Database: admin (보통)

문제 해결 플로우차트

MongoDB 연결 안 됨?
        │
        ▼
┌───────────────────────┐
│ 1. 서버 실행 중인가?   │
│    ps aux | grep mongod│
└───────────────────────┘
        │
   No   │   Yes
        │     │
        ▼     ▼
   서버 시작  ┌───────────────────────┐
              │ 2. 포트 열려 있는가?   │
              │    lsof -i :27017     │
              └───────────────────────┘
                      │
                 No   │   Yes
                      │     │
                      ▼     ▼
               방화벽 확인  ┌───────────────────────┐
                           │ 3. 인증 필요한가?      │
                           │    mongosh로 테스트    │
                           └───────────────────────┘
                                   │
                              No   │   Yes
                                   │     │
                                   ▼     ▼
                                성공!   인증 정보로 재접속

다음 단계

MongoDB 설치가 완료되었습니다! 이제 실제로 사용해볼 차례입니다.

유용한 학습 리소스

공식 문서 (가장 정확):

실습 도구:

MongoDB Compass - 공식 GUI 도구 (설치 시 함께 설치됨)
Studio 3T - 고급 GUI 도구 (무료 버전 있음)
MongoDB Playground - 웹에서 바로 실습

핵심 정리

MongoDB 로컬 설치 핵심:
────────────────────────────────────────────────────────────

✅ 운영체제별 권장 방법:
   • macOS → Homebrew
   • Windows → MSI 설치 파일
   • Linux → 공식 저장소 + apt/yum
   • 팀 프로젝트 → Docker Compose

✅ 필수 확인 사항:
   • mongod --version (서버)
   • mongosh (Shell 연결)
   • brew services list / systemctl status mongod (서비스 상태)

✅ 보안 습관:
   • 인증 활성화 (authorization: enabled)
   • 애플리케이션별 사용자 생성
   • 정기적 백업

✅ 문제 해결:
   • 로그 확인이 핵심!
   • 대부분의 문제는 서비스 미실행 또는 권한 문제

MongoDB 설치, 생각보다 어렵지 않죠?

핵심은 자신의 환경에 맞는 방법을 선택하고, 에러가 나면 로그를 확인하는 것입니다. 이제 MongoDB를 마음껏 사용하면서 NoSQL 데이터베이스의 유연함을 경험해보세요!

문제가 생기면 이 문서의 함정과 해결책 섹션을 다시 찾아보시고, 그래도 해결이 안 되면 MongoDB 공식 커뮤니티에서 도움을 받을 수 있습니다.

목차

왜 MongoDB를 로컬에 설치할까?

설치 전 알아두기

MongoDB 버전, 뭘 선택해야 할까?

시스템 요구사항

설치 방법, 어떤 걸 선택할까?

macOS에 설치하기

방법 1: Homebrew 사용 (강력 추천)

방법 2: 공식 패키지 다운로드

Windows에 설치하기

방법 1: MSI 설치 파일 (강력 추천)

방법 2: Chocolatey (패키지 관리자)

Linux에 설치하기

Ubuntu/Debian

RHEL/CentOS/Fedora

Docker로 설치하기

왜 Docker로 설치할까?

방법 1: Docker 명령어로 실행

방법 2: Docker Compose 사용 (강력 추천)

설치 확인 및 기본 사용법

설치 확인

연결 성공/실패 확인

MongoDB Shell 기본 명령어

초기 설정 가이드

1. 보안 설정: 인증 활성화

2. 애플리케이션용 사용자 생성

3. 연결 문자열 (Connection String)

4. 데이터베이스 백업 설정

함정과 해결책

함정 1: “connect ECONNREFUSED” 에러

함정 2: “Data directory not found” 에러

함정 3: “Address already in use” 에러

함정 4: “Unauthorized” 에러

함정 5: Permission Denied 에러

함정 6: MongoDB Compass가 연결 안 됨

문제 해결 플로우차트

다음 단계

추천 학습 순서

유용한 학습 리소스

핵심 정리

댓글