자습서: Azure Cosmos DB for MongoDB(vCore)와 Node.js 웹앱 연결

  • 아티클

적용 대상: MongoDB vCore

이 자습서에서는 vCore 아키텍처에서 Azure Cosmos DB for MongoDB에 연결하는 Node.js 웹 애플리케이션을 빌드합니다. MERN(MongoDB, Express, React.js, Node.js) 스택은 많은 최신 웹 애플리케이션을 빌드하는 데 사용되는 인기 있는 기술 모음입니다. Azure Cosmos DB for MongoDB(vCore)를 사용하면 이미 익숙한 MongoDB 드라이버를 사용하여 새 웹 애플리케이션을 빌드하거나 기존 애플리케이션을 마이그레이션할 수 있습니다. 이 자습서에서는 다음을 수행합니다.

  • 환경 설정
  • 로컬 MongoDB 컨테이너를 사용하여 MERN 애플리케이션 테스트
  • vCore 클러스터를 사용하여 MERN 애플리케이션 테스트
  • Azure App Service에 MERN 애플리케이션 배포

필수 조건

이 자습서를 완료하는 데 필요한 리소스는 다음과 같습니다.

  • 기존 vCore 클러스터.
  • GitHub 계정.
    • GitHub에는 모든 사용자를 위한 무료 Codespaces 시간이 제공됩니다.

개발 환경 구성

개발 컨테이너 환경은 이 프로젝트의 모든 연습을 완료하는 데 필요한 모든 종속성에서 사용할 수 있습니다. GitHub Codespaces에서 또는 Visual Studio Code를 사용하여 로컬로 개발 컨테이너를 실행할 수 있습니다.

GitHub Codespaces는 사용자 인터페이스로 웹용 Visual Studio Code를 사용하여 GitHub에서 관리하는 개발 컨테이너를 실행합니다. 가장 간단한 개발 환경의 경우, 이 학습 모듈을 완료하기 위해 올바른 개발자 도구와 종속성이 미리 설치되도록 GitHub Codespaces를 사용합니다.

중요

모든 GitHub 계정은 2개의 코어 인스턴스를 사용하여 매월 최대 60시간 동안 Codespaces를 무료로 사용할 수 있습니다.

  1. azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app GitHub 리포지토리의 main 분기에 새 GitHub Codespace를 만드는 프로세스를 시작합니다.

    GitHub Codespaces에서 열기

  2. codespace 만들기 페이지에서 codespace 구성 설정을 검토한 다음, 새 codespace 만들기를 선택합니다.

    새 codespace를 만들기 전에 확인 화면의 스크린샷

  3. codespace가 생성될 때까지 기다립니다. 이 프로세스에는 몇 분 정도 걸릴 수 있습니다.

  4. codespace에서 새 터미널을 엽니다.

    팁

    기본 메뉴를 사용하여 터미널 메뉴 옵션으로 이동한 다음, 새 터미널 옵션을 선택할 수 있습니다.

    새 터미널을 여는 codespaces 메뉴 옵션의 스크린샷

  5. 이 자습서에서 사용하는 도구의 버전을 확인합니다.

    docker --version

node --version

npm --version

az --version

    참고 항목

    이 자습서에는 사용자 환경에 미리 설치된 각 도구의 다음 버전이 필요합니다.

    도구 버전
    Docker 20.10.0 이상
    Node.JS 18.0150 이상
    NPM 9.5.0 이상
    Azure CLI 2.46.0 이상

  6. 터미널을 닫습니다.

  7. 이 자습서의 나머지 단계는 이 개발 컨테이너의 컨텍스트에서 수행됩니다.

MongoDB 컨테이너를 사용하여 MERN 애플리케이션의 API 테스트

먼저 로컬 MongoDB 컨테이너에서 샘플 애플리케이션의 API를 실행하여 애플리케이션이 작동하는지 확인합니다.

  1. Docker를 사용하여 MongoDB 컨테이너를 실행하고 일반 MongoDB 포트(27017)를 게시합니다.

    docker pull mongo:6.0

docker run --detach --publish 27017:27017 mongo:6.0

  2. 사이드바에서 MongoDB 확장을 선택합니다.

    사이드바의 MongoDB 확장 스크린샷.

  3. 연결 문자열 mongodb://localhost를 사용하여 MongoDB 확장에 새 연결을 추가합니다.

    MongoDB 확장의 연결 추가 단추 스크린샷.

  4. 연결에 성공하면 data/products.mongodb 플레이그라운드 파일을 엽니다.

  5. 모두 실행 아이콘을 선택하여 스크립트를 실행합니다.

    MongoDB 확장에 대한 플레이그라운드에서 모두 실행 단추의 스크린샷.

  6. 플레이그라운드를 실행하면 로컬 MongoDB 컬렉션의 문서 목록이 생성됩니다. 다음은 잘린 출력 예제입니다.

    [
  {
    "_id": { "$oid": "640a146e89286b79b6628eef" },
    "name": "Confira Watch",
    "category": "watches",
    "price": 105
  },
  {
    "_id": { "$oid": "640a146e89286b79b6628ef0" },
    "name": "Diannis Watch",
    "category": "watches",
    "price": 98,
    "sale": true
  },
  ...
]

    참고 항목

    개체 ID(_id)는 임의로 생성되며 잘린 예제 출력과 다릅니다.

  7. server/디렉터리에 새 .env 파일을 만듭니다.

  8. server/.env 파일에서 이 값에 대한 환경 변수를 추가합니다.

    환경 변수 값
    CONNECTION_STRING Azure Cosmos DB for MongoDB(vCore) 클러스터에 대한 연결 문자열입니다. 지금은 mongodb://localhost:27017?directConnection=true을 사용합니다. 
    CONNECTION_STRING=mongodb://localhost:27017?directConnection=true

  9. 터미널의 컨텍스트를 server/ 폴더로 변경합니다.

    cd server

  10. 노드 패키지 관리자(npm)에서 종속성을 설치합니다.

    npm install

  11. Node.js 및 Express 애플리케이션을 시작합니다.

    npm start

  12. API가 브라우저 창을 자동으로 열어 제품 문서 배열이 반환되는지 확인합니다.

  13. 추가 브라우저 탭/창을 닫습니다.

  14. 터미널을 닫습니다.

Azure Cosmos DB for MongoDB(vCore) 클러스터를 사용하여 MERN 애플리케이션 테스트

이제 애플리케이션이 Azure Cosmos DB for MongoDB(vCore)에서 원활하게 작동하는지 확인해 보겠습니다. 이 태스크의 경우 MongoDB 셸을 사용하여 기존 클러스터를 시드 데이터로 채운 다음, API의 연결 문자열을 업데이트합니다.

  1. Azure Portal에 로그인합니다(https://portal.azure.com).

  2. 기존 Azure Cosmos DB for MongoDB(vCore) 클러스터 페이지로 이동합니다.

  3. Azure Cosmos DB for MongoDB(vCore) 클러스터 페이지에서 연결 문자열 탐색 메뉴 옵션을 선택합니다.

    클러스터 페이지에 있는 연결 문자열 옵션의 스크린샷.

  4. 연결 문자열 필드의 값을 기록합니다.

    클러스터에 대한 연결 문자열 자격 증명의 스크린샷.

    Important

    포털의 연결 문자열은 사용자 이름 및 암호 값을 포함하지 않습니다. <user> 및 <password> 자리 표시자는 원래 클러스터를 만들 때 사용한 자격 증명으로 바꿔야 합니다.

  5. IDE(통합 개발 환경) 내에서 다시 새 터미널을 엽니다.

  6. mongosh 명령 및 이전에 기록한 연결 문자열을 사용하여 MongoDB 셸을 시작합니다. <user> 및 <password> 자리 표시자는 원래 클러스터를 만들 때 사용한 자격 증명으로 바꿔야 합니다.

    mongosh "<mongodb-cluster-connection-string>"

    참고 항목

    연결 문자열에 대한 특정 값을 인코딩해야 할 수 있습니다. 이 예제에서 클러스터의 이름은 msdocs-cosmos-tutorial이 고, 사용자 이름은 clusteradmin이며, 암호는 P@ssw.rd입니다. 암호에서 @ 문자는 %40을 사용하여 인코딩해야 합니다. 암호의 올바른 인코딩이 적용된 연결 문자열 예제는 다음과 같습니다.

    CONNECTION_STRING=mongodb+srv://clusteradmin:P%40ssw.rd@msdocs-cosmos-tutorial.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000

  7. 셸 내에서 다음 명령을 실행하여 데이터베이스를 만들고, 컬렉션을 만들고, 시작 데이터를 사용하여 시드합니다.

    use('cosmicworks');

db.products.drop();

db.products.insertMany([
  { name: "Confira Watch", category: "watches", price: 105.00 },
  { name: "Diannis Watch", category: "watches", price: 98.00, sale: true },
  { name: "Sterse Gloves", category: "gloves", price: 42.00 },
  { name: "Peache Sunglasses", category: "eyewear", price: 32.00, sale: false, sizes: [ "S", "M", "L" ] },
  { name: "Icento Pack", category: "bags", price: 58.00 },
  { name: "Iroowl Bracelet", category: "watches", price: 66.00 },
  { name: "Glaark Bag", category: "bags", price: 56.00, sale: true },
  { name: "Windry Mittens", category: "gloves", price: 35.00 },
  { name: "Tuvila Hat", category: "hats", price: 120.00 },
  { name: "Klinto Hat", category: "hats", subcategory: "hats-beanies", price: 65.00 }
]);

db.products.find({});

  8. 명령을 실행하면 로컬 MongoDB 컬렉션의 문서 목록이 생성됩니다. 다음은 잘린 출력 예제입니다.

    [
  {
    "_id": { "$oid": "640a146e89286b79b6628eef" },
    "name": "Confira Watch",
    "category": "watches",
    "price": 105
  },
  {
    "_id": { "$oid": "640a146e89286b79b6628ef0" },
    "name": "Diannis Watch",
    "category": "watches",
    "price": 98,
    "sale": true
  },
  ...
]

    참고 항목

    개체 ID(_id)는 임의로 생성되며 잘린 예제 출력과 다릅니다.

  9. MongoDB 셸을 종료합니다.

    exit

  10. client/디렉터리에 새 .env 파일을 만듭니다.

  11. client/.env 파일에서 이 값에 대한 환경 변수를 추가합니다.

    환경 변수 값
    CONNECTION_STRING Azure Cosmos DB for MongoDB(vCore) 클러스터에 대한 연결 문자열입니다. mongo 셸에서 사용한 것과 동일한 연결 문자열을 사용합니다. 
    CONNECTION_STRING=<your-connection-string>

  12. 터미널의 컨텍스트를 server/ 폴더로 변경하고, npm(노드 패키지 관리자)에서 종속성을 설치한 다음, 애플리케이션을 시작하여 애플리케이션이 데이터베이스 서비스를 사용하고 있는지 확인합니다.

    cd server

npm install

npm start

  13. API가 브라우저 창을 자동으로 열어 제품 문서 배열이 반환되는지 확인합니다.

  14. 추가 브라우저 탭/창을 닫습니다. 그런 다음, 터미널을 닫습니다.

Azure App Service에 MERN 애플리케이션 배포

Azure App Service에 서비스 및 클라이언트를 배포하여 애플리케이션이 엔드투엔드로 작동하는지 확인합니다. 웹앱의 비밀을 사용하여 자격 증명 및 API 엔드포인트가 포함된 환경 변수를 저장합니다.

  1. IDE(통합 개발 환경) 내에서 새 터미널을 엽니다.

  2. resourceGroupName이라는 기존 리소스 그룹의 이름에 대한 셸 변수를 만듭니다.

    # Variable for resource group name
resourceGroupName="<existing-resource-group>"

  3. serverAppName 및 clientAppName이라는 두 웹앱에 대한 셸 변수를 만듭니다.

    # Variable for randomnly generated suffix
let suffix=$RANDOM*$RANDOM

# Variable for web app names with a randomnly generated suffix
serverAppName="server-app-$suffix"
clientAppName="client-app-$suffix"

  4. 아직 로그인하지 않은 경우 az login --use-device-code 명령을 사용하여 Azure CLI에 로그인합니다.

  5. 현재 작업 디렉터리를 server/ 경로로 변경합니다.

    cd server

  6. az webapp up을 사용하여 MERN 애플리케이션의 서버 구성 요소에 대한 새 웹앱을 만듭니다.

    az webapp up \
    --resource-group $resourceGroupName \
    --name $serverAppName \
    --sku F1 \
    --runtime "NODE|18-lts"

  7. az webapp config connection-string set를 사용하여 CONNECTION_STRING이라는 서버 웹앱에 대한 새 연결 문자열 설정을 만듭니다. 이 자습서의 앞부분에서 MongoDB 셸 및 .env 파일에 사용한 연결 문자열에 대해 동일한 값을 사용합니다.

    az webapp config connection-string set \
    --resource-group $resourceGroupName \
    --name $serverAppName \
    --connection-string-type custom \
    --settings "CONNECTION_STRING=<mongodb-connection-string>"

  8. az webapp show를 사용하여 서버 웹앱의 URI를 가져와서 serverUri라는 셸 변수 이름에 저장합니다.

    serverUri=$(az webapp show \
    --resource-group $resourceGroupName \
    --name $serverAppName \
    --query hostNames[0] \
    --output tsv)

  9. npx에 NuGet의 open-cli 패키지 및 명령을 사용하여 브라우저 창에서 서버 웹앱의 URI를 엽니다. 서버 앱이 MongoDB(vCore) 클러스터의 JSON 배열 데이터를 반환하는지 확인합니다.

    npx open-cli "https://$serverUri/products" --yes

    팁

    경우에 따라 배포가 비동기적으로 완료될 수 있습니다. 예상한 내용이 표시되지 않으면 잠시 기다렸다가 브라우저 창을 새로 고칩니다.

  10. 작업 디렉터리를 client/ 경로로 변경합니다.

    cd ../client

  11. az webapp up을 사용하여 MERN 애플리케이션의 클라이언트 구성 요소에 대한 새 웹앱을 만듭니다.

    az webapp up \
    --resource-group $resourceGroupName \
    --name $clientAppName \
    --sku F1 \
    --runtime "NODE|18-lts"

  12. az webapp config appsettings set를 사용하여 REACT_APP_API_ENDPOINT라는 클라이언트 웹앱에 대한 새 앱 설정을 만듭니다. serverUri 셸 변수에 저장된 서버 API 엔드포인트를 사용합니다.

    az webapp config appsettings set \
    --resource-group $resourceGroupName \
    --name $clientAppName \
    --settings "REACT_APP_API_ENDPOINT=https://$serverUri"

  13. az webapp show를 사용하여 클라이언트 웹앱의 URI를 가져와서 clientUri라는 셸 변수 이름에 저장합니다.

    clientUri=$(az webapp show \
    --resource-group $resourceGroupName \
    --name $clientAppName \
    --query hostNames[0] \
    --output tsv)

  14. npx에 NuGet의 open-cli 패키지 및 명령을 사용하여 브라우저 창에서 클라이언트 웹앱의 URI를 엽니다. 클라이언트 앱이 서버 앱의 API에서 데이터를 렌더링하는지 확인합니다.

    npx open-cli "https://$clientUri" --yes

    팁

    경우에 따라 배포가 비동기적으로 완료될 수 있습니다. 예상한 내용이 표시되지 않으면 잠시 기다렸다가 브라우저 창을 새로 고칩니다.

  15. 터미널을 닫습니다.

리소스 정리

사용자 고유의 구독에서 작업하는 경우 프로젝트의 끝에서 더 이상 필요하지 않은 리소스를 제거하는 것이 좋습니다. 계속 실행되는 리소스에는 요금이 부과될 수 있습니다. 리소스를 개별적으로 삭제하거나 리소스 그룹을 삭제하여 전체 리소스 세트를 삭제할 수 있습니다.

  1. 전체 리소스 그룹을 삭제하려면 az group delete를 사용합니다.

    az group delete \
    --name $resourceGroupName \
    --yes

  2. az group list를 사용하여 리소스 그룹이 삭제되었는지 확인합니다.

    az group list

개발 환경 정리

개발 환경을 정리하거나 일반적인 상태로 되돌릴 수도 있습니다.

GitHub Codespaces 환경을 삭제하면 계정에 대해 얻을 수 있는 코어당 무료 사용 권한을 최대화할 수 있습니다.

  1. GitHub Codespaces 대시보드(https://github.com/codespaces)에 로그인합니다.

  2. azure-samples/msdocs-azure-cosmos-db-mongodb-mern-web-app GitHub 리포지토리에서 제공된 현재 실행 중인 codespace를 찾습니다.

    상태 및 템플릿을 포함하여 실행 중인 모든 codespaces의 스크린샷

  3. codespace에 대한 상황에 맞는 메뉴를 열고 삭제를 선택합니다.

    삭제 옵션이 강조 표시된 단일 codespace에 대한 상황에 맞는 메뉴의 스크린샷

다음 단계

MongoDB(vCore) 클러스터에 대한 첫 번째 애플리케이션을 빌드했으므로 이제 Azure Cosmos DB로 데이터를 마이그레이션하는 방법을 알아보세요.

데이터 마이그레이션