[New Hack] MongoDB to Azure DocumentDB migration WTH

.devcontainer/075-MongoDB2DocumentDB/devcontainer.json

@@ -0,0 +1,42 @@
+{
+  "name": "075-MongoDB2DocumentDB",
+  "image": "mcr.microsoft.com/devcontainers/javascript-node:18",
+  "workspaceFolder": "/workspace/075-MongoDB2DocumentDB/Student/Resources",
+  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached",
+  "hostRequirements": {
+    "cpus": 2
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "18"
+    },
+    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
+    "ghcr.io/devcontainers/features/azure-cli:1": {
+      "version": "latest",
+      "installBicep": true
+    }
+  },
+  "forwardPorts": [5001],
+  "postCreateCommand": "bash infra/post-create.sh",
+  "postStartCommand": "bash infra/post-start.sh",
+  "customizations": {
+    "codespaces": {
+      "openFiles": []
+    },
+    "vscode": {
+      "extensions": [
+        "mongodb.mongodb-vscode",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "ms-vscode.js-debug",
+        "ms-azuretools.vscode-bicep",
+        "github.copilot",
+        "github.copilot-chat"
+      ],
+      "settings": {
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
+        "editor.formatOnSave": true
+      }
+    }
+  }
+}

.gitignore

@@ -6,6 +6,9 @@
 # Mac hidden files to ignore
 ._*
 
+# Mongo migration local artifacts
+xxx-mongodb-to-azuredocumentdb-migration/Student/Resources/sampledata.archive
+
 # User-specific files
 *.suo
 *.user

075-MongoDB2DocumentDB/.wordlist.txt

@@ -0,0 +1,15 @@
+ACI
+Codespace
+Codespaces
+CosmosDB
+DMS
+DocumentDB
+ExpressRoute
+MFlix
+MongoDB
+VPN
+mflixadmin
+MFlix's
+Manish
+Sharma
+cutover

075-MongoDB2DocumentDB/Coach/README.md

@@ -0,0 +1,62 @@
+# What The Hack - Mongo DB to Azure Document DB Migration - Coach's Guide
+
+## Introduction
+
+In this hack, the students will learn how to move a MongoDB workload from MongoDB to Azure DocumentDB with minimal effort. They'll start by creating a MongoDB database from a sample and deploying a sample Node.js application. They will make sure it works as is. They will then perform a guided migration of that database to Azure using the Visual Studio Code extension for DocumentDB. Finally, they'll understand the core migration flow, validate data in the new environment, fix an issues they might encounter, and run the app against the migrated database.
+
+## Learning Objectives
+
+- Assess source database readiness and identify key migration considerations before moving data.
+- Use the DocumentDB VS Code extension to execute and monitor a database migration.
+- Compare source and target results to verify collection structure, document counts, and query behavior.
+- Update application configuration and troubleshoot common connectivity or compatibility issues after cutover.
+
+## Coach guides
+
+- Challenge 00: **[Prerequisites - Ready, Set, GO!](Solution-00.md)**
+   - Deploy the source database and get the sample application up and running
+- Challenge 01: **[Install the Azure DocumentDB migration extension for VS Code and Deploy Azure Document DB](Solution-01.md)**
+   - Install the Azure DocumentDB Migration extension in Visual Studio Code and deploy an instance of Azure DocumentDB in your Azure subscription.
+- Challenge 02: **[Migrating from MongoDB to Azure Document DB](Solution-02.md)**
+   - Use the Azure DocumentDB Migration extension to migrate data from your source MongoDB to Azure DocumentDB, then update and test the application with the new connection.
+
+## Coach Prerequisites
+
+This hack has pre-reqs that a coach is responsible for understanding and/or setting up BEFORE hosting an event. Please review the [What The Hack Hosting Guide](https://aka.ms/wthhost) for information on how to host a hack event.
+
+The guide covers the common preparation steps a coach needs to do before any What The Hack event, including how to properly configure Microsoft Teams.
+
+### Student Resources
+
+Before the hack, it is the Coach's responsibility to download and package up the contents of the `/Student/Resources` folder of this hack into a "Resources.zip" file. The coach should then provide a copy of the Resources.zip file to all students at the start of the hack.
+
+Always refer students to the [What The Hack website](https://aka.ms/wth) for the student guide: [https://aka.ms/wth](https://aka.ms/wth)
+
+**NOTE:** Students should **not** be given a link to the What The Hack repo before or during a hack. The student guide does **NOT** have any links to the Coach's guide or the What The Hack repo on GitHub.
+
+## Azure Requirements
+
+This hack requires students to have access to an Azure subscription where they can create and consume Azure resources. These Azure requirements should be shared with a stakeholder in the organization that will be providing the Azure subscription(s) that will be used by the students.
+
+- The hack deploys MongoDB on Azure Container Instances for the source MongoDB. It also deploys Azure DocumentDB to the M20 Compute Tier. This is configurable. 
+- The student should have contributor access to the Azure subscription. 
+
+## Suggested Hack Agenda 
+
+* Challenge 0 (Setup): 30-45 minutes
+* Challenge 1 (Extension + DocumentDB deployment): 45-60 minutes
+* Challenge 2 (Migration): 45-60 minutes
+* Buffer time for troubleshooting: 30 minutes per challenge
+
+This timing does not include any lecture content that you may wish to include 
+
+## Repository Contents
+
+- `./Coach`
+  - Coach's Guide and related files
+- `./Coach/Solutions`
+  - Solution files with completed example answers to a challenge
+- `./Student`
+  - Student's Challenge Guide
+- `./Student/Resources`
+  - Resource files, sample code, scripts, etc meant to be provided to students. (Must be packaged up by the coach and provided to students at start of event)

075-MongoDB2DocumentDB/Coach/Solution-00.md

@@ -0,0 +1,12 @@
+# Challenge 00 - Prerequisites - Ready, Set, GO! - Coach's Guide 
+
+**[Home](./README.md)** - [Next Solution >](./Solution-01.md)
+
+## Notes & Guidance
+
+* Have the student check their GitHub billing page early to ensure they have adequate Codespace hours remaining to do the hack.
+* It takes 3-5 minutes to start the Codespace. During this time, the students could be reading ahead in the challenges or there could be lecture. 
+* The MongoDB Atlas is not automated so there are opportunities for the students to make mistakes with the deployment for it. Make sure firewall rules there allow DMS and the student's local machine IP address so they can use the DocumentDB extension for VS Code in the next challenge(s).
+
+
+

075-MongoDB2DocumentDB/Coach/Solution-01.md

@@ -0,0 +1,11 @@
+# Challenge 01 - Install the Azure DocumentDB migration extension for VS Code and Deploy Azure Document DB - Coach's Guide 
+
+[< Previous Solution](./Solution-00.md) - **[Home](./README.md)** - [Next Solution >](./Solution-02.md)
+
+## Notes & Guidance
+
+* It may take some time to run the deployment script for Azure DocumentDB. Have the student look ahead in the challenge content or do a lecture.
+* The password in the .env file is stored in plain text. They should not use a password they use anywhere else. 
+* The firewall rules for DocumentDB may disappear on their own for Microsoft internal subscriptions.
+* The free tier for DocumentDB is not supported for Microsoft internal subscriptions.
+* Explain the difference between offline and online migration to students.

075-MongoDB2DocumentDB/Coach/Solution-02.md

@@ -0,0 +1,12 @@
+# Challenge 02 - Migrating from MongoDB to Azure Document DB - Coach's Guide 
+
+[< Previous Solution](./Solution-01.md) - **[Home](./README.md)** 
+
+## Notes & Guidance
+
+* Students will need to restart the application with `Ctrl+C` and then `npm start` after changing the connection string.
+* If the web site doesn't work because of a port conflict, they can use `ps -ef` and `kill <process-id>` to kill and restart the web application.
+* After the web site comes up, make sure they click around again to make sure the site is working
+* DMS has 2 versions, Only DMS v1 is currently visible in the portal for MongoDB (migrates to CosmosDB Mongo RU only). The DMS created from VS Code is DMS v2 (migrates to Azure DocumentDB only). Hence, you can't find DMS created from VS Code in the Azure Portal or the CLI. There should be a portal experience for DocumentDB (DMS v2) later in 2026. Once that is completed, both DMS v1 and v2 will be manageable from the Azure portal. 
+* Since the migration job runs on DMS using cloud resources, DMS can't access the local server and hence the job will fail. In the case of an on-premises source cluster, they would need to connect the on-premises server to Azure using a VPN or ExpressRoute. 
+

075-MongoDB2DocumentDB/README.md

@@ -0,0 +1,36 @@
+# What The Hack - Mongo DB to Azure Document DB Migration
+
+## Introduction
+
+In this hack, you will learn how to move a MongoDB workload from MongoDB to Azure DocumentDB with minimal effort. You'll start by creating a MongoDB database from a sample and deploying a sample Node.js application. You will make sure it works as is. You will then perform a guided migration of that database to Azure using the Visual Studio Code extension for DocumentDB. Finally, you’ll understand the core migration flow, validate data in the new environment, fix an issues you might encounter, and run the app against the migrated database.
+
+
+
+## Learning Objectives
+
+- Assess source database readiness and identify key migration considerations before moving data.
+- Use the DocumentDB VS Code extension to execute and monitor a database migration.
+- Compare source and target results to verify collection structure, document counts, and query behavior.
+- Update application configuration and troubleshoot common connectivity or compatibility issues after cutover.
+
+## Challenges
+
+- Challenge 00: **[Prerequisites - Ready, Set, GO!](Student/Challenge-00.md)**
+	 - Deploy the source database and get the sample application up and running
+- Challenge 01: **[Install the Azure DocumentDB migration extension for VS Code and Deploy Azure Document DB](Student/Challenge-01.md)**
+	 - Install the Azure DocumentDB Migration extension in Visual Studio Code and deploy an instance of Azure DocumentDB in your Azure subscription.
+- Challenge 02: **[Migrating from MongoDB to Azure Document DB](Student/Challenge-02.md)**
+	 - Use the Azure DocumentDB Migration extension to migrate data from your source MongoDB to Azure DocumentDB, then update and test the application with the new connection.
+	 - Compare the source target databases and if everything is okay, you will modify the application configuration with the new Azure DocumentDB and re-run the application
+
+## Prerequisites
+
+- Your own Azure subscription with Owner access
+- Visual Studio Code
+- Personal GitHub account
+
+## Contributors
+
+- [Pete Rodriguez](https://github.com/perktime)
+- [Mike Shelton](https://github.com/mshelt)
+- [Manish Sharma](https://github.com/manishmsfte)

075-MongoDB2DocumentDB/Student/Challenge-00.md

@@ -0,0 +1,162 @@
+# Challenge 00 - Prerequisites - Ready, Set, GO!
+
+**[Home](../README.md)** - [Next Challenge >](./Challenge-01.md)
+
+## Introduction
+
+Thank you for participating in the MongoDB to Azure DocumentDB Migration What The Hack. Before you can start hacking, you will need to set up some prerequisites.
+
+## Prerequisites
+
+In this challenge, you will set up the necessary prerequisites and environment to complete the rest of the hack, including:
+
+- [Azure Subscription](#azure-subscription)
+- [Setup Development Environment](#setup-development-environment)
+  - [GitHub Codespaces](#use-github-codespaces)
+  - [Local Workstation](#use-local-workstation)
+- [Setup MongoDB Source Database](#setup-mongodb-source-database)
+
+### Azure Subscription
+
+You will need an Azure subscription to complete this hack. If you don't have one, get a free trial here...
+- [Azure Subscription](https://azure.microsoft.com/en-us/free/)
+
+### Setup Development Environment
+
+You will need a set of developer tools to work with the sample application for this hack. 
+
+You can use GitHub Codespaces where we have a pre-configured development environment set up and ready to go for you, or you can setup the developer environment on your local workstation using DevContainers.
+
+#### Use GitHub Codespaces
+
+You must have a GitHub account to use GitHub Codespaces. If you do not have a GitHub account, you can [Sign Up Here](https://github.com/signup).
+
+GitHub Codespaces is available for developers in every organization. All personal GitHub.com accounts include a monthly quota of free usage each month. GitHub will provide users in the Free plan 120 core hours, or 60 hours of run time on a 2 core codespace, plus 15 GB of storage each month.
+
+You can see your balance of available codespace hours on the [GitHub billing page](https://github.com/settings/billing/summary).
+
+The GitHub Codespace for this hack will let you run the sample MFlix application which uses MongoDB as its database.
+
+- A GitHub repo containing the student resources and Codespace for this hack is hosted here:
+  - [MongoDB to Azure DocumentDB WTH Codespace Repo](https://aka.ms/wth/mongodb2documentdb/codespace)
+  - Please open this link and sign in with your personal Github account. 
+
+**NOTE:** Make sure you do not sign in with your enterprise managed Github account.
+
+Once you are signed in:
+- Verify that the `Dev container configuration` drop down is set to `xxx-mongodb-toazuredocumentdb-migration`
+- Click on the green "Create Codespace" button.
+
+Your Codespace environment should load in a new browser tab. It will take approximately 3-5 minutes the first time you create the codespace for it to load.
+
+- When the codespace completes loading, you should find an instance of Visual Studio Code running in your browser with the files needed for this hackathon.
+
+You are ready to setup the MongoDB source database. Skip to section: [Setup the Source MongoDB Database](#setup-the-source-mongodb-database)
+
+**NOTE:** If you close your Codespace window, or need to return to it later, you can go to [GitHub Codespaces](https://github.com/codespaces) and you should find your existing Codespaces listed with a link to re-launch it.
+
+#### Use Local Workstation
+
+**NOTE:** You can skip this section if are using GitHub Codespaces!
+
+If you want to setup this environment on your local workstation, expand the section below and follow the requirements listed. We have provided a Dev Container that will load the development environment on your local workstation if you do not want to use GitHub Codespaces.  
+
+<details markdown=1>
+<summary markdown="span"><strong>Click to expand/collapse Local Workstation Setup</strong></summary>
+
+##### Download Student Resources
+
+The Dev Container with the Mflix app is available in a Student Resources package.
+
+- [Download `Resources.zip`](https://aka.ms/wth/mongodb2documentdb/resources) package to your local workstation. 
+
+The rest of the challenges will refer to the relative paths inside the Codespace or `Resources.zip` file where you can find the various resources to complete the challenges.
+
+##### Set Up Local Dev Container
+
+You will next be setting up your local workstation so that it can use Dev Containers. A Dev Container is a Docker-based environment designed to provide a consistent and reproducible development setup. The VS Code Dev Containers extension lets you easily open projects inside a containerized environment. 
+
+**NOTE:** On Windows, Dev Containers run in the Windows Subsystem for Linux (WSL). 
+
+On Windows and Mac OS (**NOTE:** only tested on Apple Silicon):
+- (Windows only) Install the Windows Subsystem for Linux along with a Linux distribution such as Ubuntu. You will need to copy the `Resources.zip` to your Linux home directory and unzip it there. 
+- Download and install Docker Desktop
+- Open the root folder of the Student Resources package in Visual Studio Code
+- You should get prompted to re-open the folder in a Dev Container. You can do that by clicking the Yes button, but if you miss it or hit no, you can also use the Command Palette in VS Code and select `Dev Containers: Reopen in Container`
+
+</details>
+<br/>
+
+### Setup MongoDB Source Database
+
+You can choose to deploy a MongoDB instance in Docker container in Azure Container Instances with a deployment script or if you prefer, you can set up the source database in MongoDB Atlas instead manually. 
+
+#### Deploy MongoDB in Azure Container Instances
+
+Login to the Azure CLI from the terminal in your GitHub Codespace or local workstation:
+
+```
+az login
+```
+**NOTE:** If you have access to multiple Azure subscriptions, you may need to switch to the subscription you want to work with.
+
+If you are using GitHub Codespaces, the `az login` command will use a Device Code to login. If your organization's Azure policy prevents this, follow these steps first before you run the deployment:
+- Open your [Codespace in Visual Studio Code Desktop](https://docs.github.com/en/codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code)
+- From the terminal in Visual Studio Code, run these commands to login:
+```
+CODESPACES=false
+az login
+```
+Perform the following steps to create an instance of MongoDB in your Azure subscription
+
+- Open a New Terminal window in VS Code
+- Type the following commands to deploy MongoDB in a container
+
+  ```
+  cd infra 
+  chmod +x deploy-source-db.sh
+  ./deploy-source-db.sh --administratorLogin mflixadmin --administratorPassword <password>
+  ```
+
+Optional: If you need to, you can specify the `resourceGroupName` and `location` as arguments to the `deploy-target-db.sh` script as follows. ***Note***: It defaults to `rg-mflix-documentdb` and `eastus2` for those, respectively:
+
+  ```
+  cd infra 
+  chmod +x deploy-source-db.sh
+  ./deploy-source-db.sh --resourceGroupName <your_resource_group_name> --location westus --administratorLogin mflixadmin --administratorPassword <password>
+  ```
+#### Deploy MongoDB in Atlas
+
+If you want to deploy to MongoDB Atlas instead, go to this link: [Get Started With Atlas](https://www.mongodb.com/docs/atlas/getting-started/).
+- You will probably want to follow the steps mentioned in the Atlas UI tab (as opposed to the Atlas CLI but you can figure that out if you want).
+- You will need to also load the sample MFlix application into your Atlas cluster.
+- You will need to modify the MFlix's `.env` file with your MongoDB connection string from Atlas. 
+
+#### Run the MFlix Application
+
+The sample MFlix application is implemented as a Node.js application. You will be running this application either within your GitHub Codespace or Dev Container for simplicity. In practice, it would be deployed as a container into Azure. 
+
+In a Terminal session in VSCode, navigate to the `MFlix` folder and run the application:
+
+```
+# Starts up the MFlix web application 
+npm start
+```
+
+You should see a message in Visual Studio Code that your Application running on port 5001 is available. Click the `Open in Browser` button to open the MFlix application. Try it out!
+
+***Note***: If you need the username and password you chose during the MongoDB deployment, they are stored in the `MFlix/.env` file in the `MFLIX_DB_URI` connection string. 
+
+## Success Criteria
+
+To complete this challenge successfully, you should:
+
+- Verify that the MFlix sample application is running in your browser using your source MongoDB database.
+
+## Learning Resources
+
+- [MongoDB Atlas - Get Started](https://www.mongodb.com/docs/atlas/getting-started/)
+- [Compare Azure DocumentDB to MongoDB Atlas](https://learn.microsoft.com/en-us/azure/documentdb/compare-mongodb-atlas)
+- [MongoDB Connection String URI Format](https://www.mongodb.com/docs/manual/reference/connection-string/)
+- [Azure DocumentDB for MongoDB](https://learn.microsoft.com/azure/cosmos-db/mongodb/)
+- [Azure DocumentDB Migration with Azure Data Studio Extension](https://learn.microsoft.com/azure/cosmos-db/mongodb/migrate)