Update docs for containerisation (microsoft#12)

* Update README for containers

* Update port numbers for each app for containerization

* Fix typo

Author: justinyoo

README.md

@@ -96,3 +96,4 @@ Check out the complete example of each application. They're also vibe-coded with
 - [GitHub Copilot: MCP](https://code.visualstudio.com/blogs/2025/05/12/agent-mode-meets-mcp)
 - [GitHub Copilot: Custom Instructions](https://code.visualstudio.com/docs/copilot/copilot-customization)
 - [GitHub Copilot: Changing AI Models](https://docs.github.com/en/copilot/using-github-copilot/ai-models/changing-the-ai-model-for-copilot-chat?tool=vscode)
+- [Curated MCP Servers](https://github.com/modelcontextprotocol/servers)

complete/README.md

@@ -26,7 +26,7 @@ Refer to the [README](../README.md) doc for preparation.
 1. Run the containerized apps.
 
     ```bash
-    docker compose up -d
+    docker compose up --build -d
     ```
 
 1. Open a web browser and navigate to `http://localhost:3000`.

complete/compose.yaml

@@ -15,7 +15,7 @@ services:
       dockerfile: Dockerfile.dotnet
     container_name: contoso-frontend
     ports:
-      - "3000:8080"
+      - "3030:8080"
     depends_on:
       - contoso-backend
     environment:

docs/.vscode/mcp.json

@@ -8,6 +8,13 @@
     }
   ],
   "servers": {
+    "context7": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@upstash/context7-mcp"
+      ]
+    },
     "Framelink Figma MCP": {
       "command": "npx",
       "args": [

docs/00-setup.md

@@ -65,7 +65,7 @@ Refer to the [README](../README.md) doc for preparation.
 
    If you see something different from above, delete the GitHub Codespace instance and recreate it.
 
-1. Move down to the [Check GitHub Copilot Agent Mode](#check-github-copilot-agent-mode) section.
+1. Move down to the [Set-up MCP Servers](#set-up-mcp-servers) section.
 
 **👇👇👇 Instead, if you'd like to use VS Code on your local machine, follow the instruction below. The section below doesn't apply to those who use GitHub Codespaces. 👇👇👇**
 
@@ -255,6 +255,37 @@ Refer to the [README](../README.md) doc for preparation.
     code --install-extension "github.copilot" --force && code --install-extension "github.copilot-chat" --force
     ```
 
+### Set-up MCP Servers
+
+1. Set the environment variable of `$REPOSITORY_ROOT`.
+
+   ```bash
+   # bash/zsh
+   REPOSITORY_ROOT=$(git rev-parse --show-toplevel)
+   ```
+
+   ```powershell
+   # PowerShell
+   $REPOSITORY_ROOT = git rev-parse --show-toplevel
+   ```
+
+1. Copy MCP server settings.
+
+    ```bash
+    # bash/zsh
+    cp -r $REPOSITORY_ROOT/docs/.vscode/. \
+          $REPOSITORY_ROOT/.vscode/
+    ```
+
+    ```powershell
+    # PowerShell
+    Copy-Item -Path $REPOSITORY_ROOT/docs/.vscode/* `
+              -Destination $REPOSITORY_ROOT/.vscode/ -Recurse -Force
+    ```
+
+1. Open Command Palette by typing F1 or `Ctrl`+`Shift`+`P` on Windows or `Cmd`+`Shift`+`P` on Mac OS, and search `MCP: List Servers`.
+1. Choose `context7` then click `Start Server`.
+
 ## Check GitHub Copilot Agent Mode
 
 1. Click the GitHub Copilot icon on the top of GitHub Codespace or VS Code and open GitHub Copilot window.

docs/01-python.md

@@ -29,6 +29,7 @@ Refer to the [README](../README.md) doc for preparation.
    ![GitHub Copilot Agent Mode](./images/setup-03.png)
 
 1. Select model to either `GPT-4.1` or `Claude Sonnet 4`.
+1. Make sure that you've configured [MCP Servers](./00-setup.md#set-up-mcp-servers).
 
 ### Prepare Custom Instructions
 
@@ -66,6 +67,7 @@ Refer to the [README](../README.md) doc for preparation.
     ```text
     I'd like to write a Python application. But before that, I need to set up a virtual environment. Follow the instructions below.
 
+    - Use context7.
     - Your working directory is `python`.
     - Identify all the steps first, which you're going to do.
     - Use `.venv` for the virtual environment.
@@ -81,6 +83,7 @@ Refer to the [README](../README.md) doc for preparation.
     ```text
     I'd like to build a FastAPI application as a backend API. Carefully read the entire PRD and `openapi.yaml`. Then, follow the instructions below.
     
+    - Use context7.
     - Your working directory is `python`.
     - Identify all the steps first, which you're going to do.
     - Use FastAPI as the API app framework.

docs/02-javascript.md

@@ -32,6 +32,7 @@ Refer to the [README](../README.md) doc for preparation.
    ![GitHub Copilot Agent Mode](./images/setup-03.png)
 
 1. Select model to either `GPT-4.1` or `Claude Sonnet 4`.
+1. Make sure that you've configured [MCP Servers](./00-setup.md#set-up-mcp-servers).
 
 ### Prepare Custom Instructions
 
@@ -77,35 +78,10 @@ Refer to the [README](../README.md) doc for preparation.
     - Use the port number of `3000`.
     ```
 
-### Set-up Figma MCP Server
+### Prepare Figma MCP Server
 
+1. Make sure that you've configured [MCP Servers](./00-setup.md#set-up-mcp-servers).
 1. Get the personal access token (PAT) from [Figma](https://www.figma.com/).
-1. Set the environment variable of `$REPOSITORY_ROOT`.
-
-   ```bash
-   # bash/zsh
-   REPOSITORY_ROOT=$(git rev-parse --show-toplevel)
-   ```
-
-   ```powershell
-   # PowerShell
-   $REPOSITORY_ROOT = git rev-parse --show-toplevel
-   ```
-
-1. Copy MCP server settings.
-
-    ```bash
-    # bash/zsh
-    cp -r $REPOSITORY_ROOT/docs/.vscode/. \
-          $REPOSITORY_ROOT/.vscode/
-    ```
-
-    ```powershell
-    # PowerShell
-    Copy-Item -Path $REPOSITORY_ROOT/docs/.vscode/* `
-              -Destination $REPOSITORY_ROOT/.vscode/ -Recurse -Force
-    ```
-
 1. Open Command Palette by typing F1 or `Ctrl`+`Shift`+`P` on Windows or `Cmd`+`Shift`+`P` on Mac OS, and search `MCP: List Servers`.
 1. Choose `Framelink Figma MCP` then click `Start Server`.
 1. Enter the PAT you get issued from Figma.
@@ -130,10 +106,12 @@ Refer to the [README](../README.md) doc for preparation.
     ```text
     I'd like to build a React web app. Follow the instructions below.
 
+    - Use context7.
     - Your working directory is `javascript`.
     - Identify all the steps first, which you're going to do.
     - There's a backend API app running on `http://localhost:5050`.
     - Use `openapi.yaml` that describes all the endpoints and data schema.
+    - Use the port number of `3000`.
     - Create all the UI components defined in this link: {{FIGMA_SECTION_LINK}}.
     - DO NOT add anything not defined in `openapi.yaml`.
     - DO NOT modify anything defined in `openapi.yaml`.
@@ -159,7 +137,7 @@ Refer to the [README](../README.md) doc for preparation.
     If app running fails, analyze the issues and fix them.
     ```
 
-1. Open a web browser and navigate to `http://localhost:3030`.
+1. Open a web browser and navigate to `http://localhost:3000`.
 1. Verify if both frontend and backend apps are running properly.
 1. Click the `[keep]` button of GitHub Copilot to take the changes.
 

docs/03-java.md

@@ -31,6 +31,7 @@ Refer to the [README](../README.md) doc for preparation.
    ![GitHub Copilot Agent Mode](./images/setup-03.png)
 
 1. Select model to either `GPT-4.1` or `Claude Sonnet 4`.
+1. Make sure that you've configured [MCP Servers](./00-setup.md#set-up-mcp-servers).
 
 ### Prepare Custom Instructions
 
@@ -74,6 +75,7 @@ Refer to the [README](../README.md) doc for preparation.
     ```text
     I'd like to scaffold a Spring Boot app. Follow the instructions below.
 
+    - Use context7.
     - Your working directory is `java`.
     - Identify all the steps first, which you're going to do.
     - Use Spring Boot CLI to create the Spring Boot app project.
@@ -101,6 +103,7 @@ Refer to the [README](../README.md) doc for preparation.
     ```text
     Now, we're migrating the existing FastAPI-based API app to Spring Boot API app. Carefully read the entire PRD and `openapi.yaml`. Follow the instructions below for the migration.
     
+    - Use context7.
     - The existing FastAPI application is located at `python`.
     - Your working directory is `java/springapp`.
     - Identify all the steps first, which you're going to do.
@@ -118,12 +121,31 @@ Refer to the [README](../README.md) doc for preparation.
     ```
 
 1. Click the `[keep]` button of GitHub Copilot to take the changes.
+1. Once migration is over, use prompt like below to verify the migration result.
+
+    ```text
+    I'd like to build the Spring Boot app. Follow the instructions.
+
+    - Use context7.
+    - Build the Spring Boot app and verify if the app is built properly.
+    - If building the app fails, analyze the issues and fix them.
+    ```
+
+   > **NOTE**:
+   >
+   > - Until the build succeeds, iterate this step.
+   > - If the build keeps failing, check out the error messages and ask them to GitHub Copilot Agent to figure them out.
+
+1. Click the `[keep]` button of GitHub Copilot to take the changes.
+
+### Verify Spring Boot Backend App
+
 1. Once the application is built, verify if it's written properly or not.
 
     ```text
     Run the Spring Boot app and verify if the app is properly running. Also verify the OpenAPI endpoint renders exactly the same content as `openapi.yaml`.
 
-    If app running fails, analyze the issues and fix them.
+    If app running fails, analyze the issues and fix them. Use context7.
     ```
 
 1. Open a web browser and navigate to `http://localhost:8080`.

docs/04-dotnet.md

@@ -31,6 +31,7 @@ Refer to the [README](../README.md) doc for preparation.
    ![GitHub Copilot Agent Mode](./images/setup-03.png)
 
 1. Select model to either `GPT-4.1` or `Claude Sonnet 4`.
+1. Make sure that you've configured [MCP Servers](./00-setup.md#set-up-mcp-servers).
 
 ### Prepare Custom Instructions
 
@@ -68,12 +69,13 @@ Refer to the [README](../README.md) doc for preparation.
     ```text
     I'd like to scaffold a Blazor web app. Follow the instructions below.
 
+    - Use context7.
     - Your working directory is `dotnet`.
     - Identify all the steps first, which you're going to do.
     - Show me the list of .NET projects related to Blazor and ask me to choose.
     - Generate a Blazor project.
     - Use the project name of `Contoso.BlazorApp`.
-    - Update `launchSettings.json` to change the port number of `3030` for HTTP, `43030` for HTTPS.
+    - Update `launchSettings.json` to change the port number of `3031` for HTTP, `43031` for HTTPS.
     - Create a solution, `ContosoWebApp`, and add the Blazor project into this solution.
     - Build the Blazor app and verify if the app is built properly.
     - Run this Blazor app and verify if the app is running properly.
@@ -90,9 +92,11 @@ Refer to the [README](../README.md) doc for preparation.
     ```text
     Now, we're migrating the existing React-based web app to Blazor web app. Follow the instructions below for the migration.
     
+    - Use context7.
     - The existing React application is located at `javascript`.
     - Your working directory is `dotnet/Contoso.BlazorApp`.
     - Identify all the steps first, which you're going to do.
+    - There's a backend API app running on `http://localhost:8080`.
     - Analyze the application structure of the existing React app.
     - Migrate all the React components to Blazor ones. Both corresponding components should be as exactly close to each other as possible.
     - Migrate all necessary CSS elements from React to Blazor.
@@ -103,6 +107,9 @@ Refer to the [README](../README.md) doc for preparation.
 1. Once migration is over, use prompt like below to verify the migration result.
 
     ```text
+    I'd like to build the Blazor app. Follow the instructions.
+
+    - Use context7.
     - Build the Blazor app and verify if the app is built properly.
     - If building the app fails, analyze the issues and fix them.
     ```
@@ -113,14 +120,36 @@ Refer to the [README](../README.md) doc for preparation.
    > - If the build keeps failing, check out the error messages and ask them to GitHub Copilot Agent to figure them out.
 
 1. Click the `[keep]` button of GitHub Copilot to take the changes.
-
 1. Once the build succeeds, use prompt like below to verify the migration result.
 
     ```text
+    I'd like to run the Blazor app. Follow the instructions.
+
+    - Use context7.
     - Run this Blazor app and verify if the app is running properly.
+    - Ignore backend API app connection error at this stage.
     - If running the app fails, analyze the issues and fix them.
     ```
 
+### Verify Blazor Frontend App
+
+1. Make sure that the Spring Boot backend app is up and running.
+
+    ```text
+    Run the Spring Boot backend API, which is located at the `java` directory.
+    ```
+
+1. Click the `[keep]` button of GitHub Copilot to take the changes.
+1. Verify if it's built properly or not.
+
+    ```text
+    Run the Blazor app and verify if the app is properly running.
+
+    If app running fails, analyze the issues and fix them.
+    ```
+
+1. Open a web browser and navigate to `http://localhost:3031`.
+1. Verify if both frontend and backend apps are running properly.
 1. Click the `[keep]` button of GitHub Copilot to take the changes.
 
 ---

docs/05-containerization.md

@@ -32,6 +32,7 @@ Refer to the [README](../README.md) doc for preparation.
    ![GitHub Copilot Agent Mode](./images/setup-03.png)
 
 1. Select model to either `GPT-4.1` or `Claude Sonnet 4`.
+1. Make sure that you've configured [MCP Servers](./00-setup.md#set-up-mcp-servers).
 
 ### Prepare Custom Instructions
 
@@ -139,7 +140,7 @@ Refer to the [README](../README.md) doc for preparation.
     ```text
     Use the container image just built, run a container and verify if the app is running properly.
     
-    - Use the host port of `3000`.
+    - Use the host port of `3030`.
     ```
 
 1. Make sure that both frontend and backend apps are NOT communicating with each other because they don't know each other yet. Run the prompt like below.
@@ -162,7 +163,7 @@ Refer to the [README](../README.md) doc for preparation.
     - Create `compose.yaml` as the Docker Compose file.
     - Use `contoso` as the network name.
     - Use `contoso-backend` as the container name of the Java app. Its target port is 8080, and host port is 5050.
-    - Use `contoso-frontend` as the container name of the .NET app. Its target port is 8080, and host port is 3000.
+    - Use `contoso-frontend` as the container name of the .NET app. Its target port is 8080, and host port is 3030.
     ```
 
 1. Once the `compose.yaml` file is created, run it and verify if both apps are running properly.
@@ -171,6 +172,8 @@ Refer to the [README](../README.md) doc for preparation.
     Now, run the Docker compose file and verify if the apps are running properly.
     ```
 
+1. Open a web browser and navigate to `http://localhost:3030`, and verify if the apps are up and running properly.
+
 ---
 
 Congratulations! 🎉 You've completed all the workshop sessions successfully!