Merge pull request #345 from cyz/contoso-javascript

Hack Together: Speaker resources (Codespaces & SWA)

devops-devtools/contoso-real-estate/README.md

@@ -0,0 +1,17 @@
+# Community Event-In-A-Box
+
+The event organization guide is a step-by-step guide to help you organize a successful event. It includes tips on how to find speakers, how to promote your event, and more.
+
+You will also find a list of presentations and workshops that you can use to present at your event. These presentations and workshops are based on the **Contoso Real Estate** project. This is a great opportunity to share knowledge about cloud-native applications within your community!
+
+## 📚 Event organization
+Organizing an event is always an adventure, and to assist you, we have created a guide with tips and suggestions to help you organize a successful event.
+
+### Get Started
+
+| Resource      | Description |
+| ----------- | ----------- |
+| **[Event Checklist](event-organization/README.md)**      | A quick guide for community leaders, with tips on speakers, promotion, and more. |
+| **Code of Conduct**   | A CoC is important to ensure that all participants feel safe and comfortable during the event. Be inspired by the [Reactor Code of Conduct](https://developer.microsoft.com/reactor/CodeOfConduct/).       |
+| **[Creative](event-organization/Creative)**   | Assets for promotion on social media, YouTube and Meetup      |
+| **Content**   | [Presentation](content/presentations) and [workshop](content/challenge-project) to build an API with Azure Functions and Deploy the `portal` project using Azure Static Web App CLI      |

devops-devtools/contoso-real-estate/content/challenge-project/00-prepare.md

@@ -0,0 +1,34 @@
+# 🚀 Prepare for the challenge
+
+You will use GitHub Codespaces to work on the Contoso Real Estate `portal` project.
+
+## What is GitHub Codespaces?
+
+GitHub Codespaces is a cloud-hosted development environment. When you work in a codespace, the environment you're working in is created using a development container, or dev container, hosted on a virtual machine.
+
+Development containers, or dev containers, are Docker containers that are specifically configured to provide a complete development environment.
+
+You can configure the dev container for a repository so that codespaces created for that repository provide a custom development environment, complete with all the tools and runtimes you need to work on a specific project.
+
+The diagram below, taken directly from the official [Visual Studio Code](https://code.visualstudio.com/docs/remote/containers/?WT.mc_id=academic-101248-cyzanon) documentation, illustrates this:
+
+![Dev Container Diagram](./images/dev-container.png)
+
+The Contoso Real Estate project is optimized for use with GitHub Codespaces, a cloud-hosted development environment from GitHub.
+
+
+## Getting started
+
+1. To get started, you will need a GitHub account. If you don't have an account, create one for free at [github.com](https://github.com/).
+
+2. Activate the [GitHub Codespaces](https://docs.github.com/codespaces/) service on your GitHub account. Codespaces offers 60 hours of free usage per month.
+
+3. You will need to make a copy of the template repository in your GitHub account. To do this, you will need to access the [repository](https://github.com/Azure-Samples/contoso-real-estate) and select the `Fork` button. At the end of the fork of the repository, you will have a copy of the project in your GitHub account. You will use this repository to develop the hands-on.
+
+4. On the repository page that was created, click the `Code` button and, in the Codespaces tab, click `Create codespace on main`. In a few moments, Codespaces will create a development environment for you.
+
+5. When Codespaces finishes creating the development environment, you will see a Visual Studio Code window in the browser. You can use Visual Studio Code in the browser to develop the application.
+
+---
+
+[**➡️ Exercise 1: Analyzing the portal project**](./01-analyzing-portal.md)

devops-devtools/contoso-real-estate/content/challenge-project/01-analyzing-portal.md

@@ -0,0 +1,71 @@
+# 🔎 Exercise 1: Analyzing the `portal` project
+
+The `portal` of the Contoso Real Estate project is a simulation of a real estate agency website where you can view the properties available for sale, rent, or buy. The architecture of the project was designed in a composable architecture.
+
+<img src="./images/composable-architecture-example.png" title="Composable Architecture Diagram" height="450" />
+
+Composable architecture is a software architecture that divides the application into smaller parts, where each part is responsible for a specific functionality. This architecture is also known as micro frontends.
+
+**Advantages of using composable architecture:**
+
+- **Reusability**: components can be reused in different parts of the application.
+- **Scalability**: the application can be scaled horizontally, that is, it can be divided into smaller parts, and each part can be developed by a different team.
+- **Maintainability**: the application can be maintained more easily as each component is responsible for a specific functionality.
+
+## Project architecture
+
+The Contoso Real Estate project is composed of three main parts:
+
+- `portal`: is the main project, where it contains the home page and the components that will be used on all pages.
+- `blog`: is the project that contains the real estate blog. In this project, `Strapi` is used as a CMS to manage blog posts.
+- `api`: is the project that contains the APIs that will be used in the `portal` project.
+
+![Contoso Real Estate Diagram](./images/e2e-full-horizontal.drawio.png)
+
+### The `portal` components
+
+This project was developed using Angular, and you will learn how it works, and how to run and deploy it using the Azure Static Web Apps CLI in Codespaces.
+
+Accessing the `packages/portal/src/app` folder, you will see the components that make up the `portal`:
+
+- `app`: main component of the application, responsible for rendering the other components.
+  - `about`: about page
+  - `authentication`: login page (authentication)
+  - `checkoutpage`: checkout page
+  - `homepage`: home page
+  - `profile`: user profile page
+  - `rentalpage`: rental page
+  - `searchpage`: search page
+  - `shared`: folder that contains the components of universal use in the application, such as buttons, inputs, etc.
+
+![Componentes](./images/gif-arquitetura-portal.gif)
+
+### Environment variables
+
+Within the `portal` project, we can see a folder called environments, which contains the configuration needed to run the project locally (or in Codespaces in this case), or in production. This is a good practice to avoid exposing sensitive data here, as these values are packaged within the application and can be retrieved easily.
+
+For example, observe the excerpt below:
+
+<details><summary><b>environments/environmet.ts</b></summary>
+<br/>
+
+  ```ts
+    export const environment = {
+      production: false,
+      blogUrl: 'http://localhost:3000',
+      isCodespaces: process.env["CODESPACE_NAME"] ? true : false,
+      strapiGraphQlUriInCodespace: `https://${process.env["CODESPACE_NAME"]}-1337.${process.env["GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN"]}/graphql`,
+      strapiGraphQlUriFallback: 'http://localhost:1337/graphql'
+    };
+  ```
+
+</details>
+<br/>
+
+As you can see, the `portal` is related to another scenario, which is the `Blog-CMS`. In this scenario, `Strapi` is used as a CMS to manage blog posts, but in this tutorial, we will focus only on the `portal`.
+
+In the next exercise, you will learn how to run the `portal` project using the Azure Static Web Apps CLI.
+
+---
+
+[**➡️ Exercise 2: Working with Azure Static Web App CLI**](./02-exercise-swa-cli.md)

devops-devtools/contoso-real-estate/content/challenge-project/02-exercise-swa-cli.md

@@ -0,0 +1,156 @@
+# 💻 Exercise 2: Working with Azure Static Web App CLI
+
+In this exercise, you'll learn how to run the **Portal** project in Codespaces and how to use the Azure Static Web Apps CLI to handle communication between the frontend and backend.
+
+## What is Azure Static Web App CLI?
+
+The **[Azure Static Web Apps (SWA) CLI](https://github.com/Azure/static-web-apps-cli/?WT.mc_id=academic-101248-cyzanon)** is an open-source command-line tool that simplifies local development and deployment to Azure Static Web Apps. It allows you to run your app locally or in a dev container, which in this case is GitHub Codespace, and then deploy your app to a production environment with just one command.
+
+## How does the communication between frontend and backend work?
+
+When we use the Azure Static Web CLI, we can establish communication between the Back-End and Front-End through the file: `swa-cli.config.json`.
+
+This file can be generated once you have globally installed the package: **[@azure/static-web-apps-cli](https://www.npmjs.com/package/@azure/static-web-apps-cli)**, by executing the following command inside the folder: **Portal**.
+
+```bash
+swa init
+```
+
+Please see the step-by-step creation of the file in the image below:
+
+![SWA init Contoso](./images/swa-init-contoso.gif)
+
+Once the file is generated according to the project settings, please observe in the code below that the `swa-cli.config.json` file has the following properties:
+
+<details><summary><b>packages/portal/swa-cli.config.json</b></summary>
+<br/>
+
+  ```json
+    {
+      "$schema": "https://aka.ms/azure/static-web-apps-cli/schema",
+      "configurations": {
+        "contoso-real-estate": {
+          "appLocation": ".",
+          "apiLocation": "../api",
+          "outputLocation": "dist/contoso-app",
+          "appBuildCommand": "npm run build",
+          "apiBuildCommand": "npm run build",
+          "run": "npm start",
+          "appDevserverUrl": "http://localhost:4200",
+          "apiDevserverUrl": "http://127.0.01:7071"
+        }
+      }
+    }
+  ```
+</details>
+<br/>
+
+The backend is located in the `packages/api` folder and it is defined in the `apiLocation` property. The frontend is located in the `packages/portal` folder and it is defined in the `appLocation` property. In both cases, the `appdevserverUrl` and `apiDevserverUrl` properties point to the URLs of the development servers.
+
+The Contoso Real Estate project API was developed in Azure Functions and Azure Cosmos DB (MongoDB API). The Azure Static Web Apps CLI automatically runs the Azure Functions emulator when it detects that an Azure Functions API is used in the project.
+
+## How to run the `portal` project?
+
+We do not recommend running this project locally, as it requires a number of configurations to work. To optimize your learning, we recommend using **[Codespaces](https://github.com/features/codespaces)** which will create a development container for you. And the best part of all: without you having to install anything on your machine.
+
+> Codespaces offers 60 free hours of usage per month. After this period, you will be charged an hourly rate. To learn more, visit [Codespaces](https://github.com/features/codespaces).
+
+To run the project in your Visual Studio Code in Codespaces, follow the steps below:
+
+1. As all the scenarios of the project are coupled, so that we can visualize what was created in the portal, it will be necessary to perform the following steps:
+  - Open the Visual Studio Code terminal and, at the root of the Contoso project, run the commands `npm install && npm start` to install the project dependencies and start the servers.
+
+  > _Note: Codespaces will show a number of windows on the right side of the screen as it starts up all the servers. This is expected and normal._
+
+2. Once all the development servers have started, the following URLs will be available:
+
+| Application    | URL                                                      | Port |
+| -------------- | -------------------------------------------------------- | ---- |
+| Portal         | https://YOUR-REPO-4280.preview.app.github.dev:4280       | 4280 |
+| Blog           | https://YOUR-REPO-3000.preview.app.github.dev:3000       | 3000 |
+| Strapi CMS     | https://YOUR-REPO-1337.preview.app.github.dev:1337/admin | 1337 |
+| Serverless API | https://YOUR-REPO-7071.preview.app.github.dev:7071/api/  | 7071 |
+| Stripe API     | https://YOUR-REPO-4242.preview.app.github.dev:4242       | 4242 |
+
+> _Note: The URLs above are just examples. The URLs will be different for your fork. The ports, however, will be the same._
+
+3. To view the project, go to the `Ports` tab of the terminal and click on the portal link, which will be port `4280` (the default port of the ASWA), to see the portal home page.
+
+![Terminal Ports](./images/terminal-ports.png)
+
+If you want to see the portal, go to the `Ports` tab of the terminal and click on the portal link, which will be port `4280`, to see the portal home page. The page will be blank, as you need to integrate the API with the portal.
+
+The example below shows the portal home page with the sample data.
+
+![Portal Home Page](./images/gif-portal-contoso.gif)
+
+### Understanding the `Portal` project execution
+
+As explained in the previous item, the Contoso project was developed in a **Composable Architecture** model; that is, it is composed of several components, where each component is responsible for a specific functionality. **For this reason, the execution of this project is coupled.**
+
+**How can we check this?**
+
+Open the `package.json` file at the root of the Contoso project and observe the scripts below:
+
+<details><summary><b>packages/portal/package.json</b></summary><br/>
+
+  ```json
+    "scripts": {
+      "start": "concurrently npm:start:* --kill-others",
+      "start:services": "docker compose up",
+      "start:api": "npm run start --workspace=api",
+      "start:website": "npm run start:swa --workspace=portal",
+      "test": "npm run test -ws --if-present",
+      "build": "npm run build -ws --if-present",
+      "format": "prettier --write .",
+      "format:check": "prettier --check .",
+      "lint": "npm run lint -ws --if-present",
+      "lint:fix": "npm run lint:fix -ws --if-present",
+      "clean": "rimraf \"packages/**/*.tsbuildinfo\"",
+      "clean:install": "rimraf \"packages/**/node_modules\" \"node_modules\" && npm install"
+    }
+  ```
+</details>
+<br/>
+
+Checking the scripts:
+
+**Docker compose**
+
+```json
+  "start:services": "docker compose up"
+```
+
+This file is responsible for starting the docker services, which are Strapi CMS and Stripe API. In addition, this `docker compose` is configured to start the Azure Database for PostgreSQL database of Strapi CMS and the Stripe API, and, in the API, it is configured to start the Azure Cosmos DB database integrated with MongoDB.
+
+**API**
+```json
+  "start:api": "npm run start --workspace=api"
+```
+
+Responsible for running the `API` project.
+
+**Portal**
+```json
+  "start:website": "npm run start:swa --workspace=portal"
+```
+
+Responsible for running the `portal` project.
+
+#### Understanding the Heart of the SWA CLI: Reverse Proxy
+
+This is the heart of the SWA CLI. It intercepts and forwards HTTP requests to the right components based on purpose:
+
+- `/.auth/**` requests => forwarded to the Auth emulator server.
+- `/api/**` requests => forwarded to the API backend (if configured).
+- `/**` => all other requests forwarded to the static assets content server.
+
+![Azure Static Web Apps CLI - Reserve Proxy](./images/swa-cli-ports.png)
+
+That's why we can connect the portal to the API without having to configure anything. The SWA CLI does this for us. You can learn more about the Azure Static Web Apps CLI at [https://azure.github.io/static-web-apps-cli/docs/intro/](https://azure.github.io/static-web-apps-cli/docs/intro/?WT.mc_id=academic-101248-cyzanon).
+
+In the next exercise, you will learn how to deploy the `portal` project on Azure Static Web Apps.
+
+---
+
+[**➡️ Exercise 3: Deploy on Azure Static Web App**](./03-exercise-portal-deploy.md)

devops-devtools/contoso-real-estate/content/challenge-project/03-exercise-portal-deploy.md

@@ -0,0 +1,142 @@
+# ☁️ Exercise 3: Deploy on Azure Static Web App
+
+In this exercise, you will learn how to deploy the `portal` project on Azure using the Azure Static Web Apps CLI and GitHub Actions. You'll need to use your Azure account for this exercise. If you don't have an account, create a free [Azure Free Trial](https://azure.microsoft.com/free/?WT.mc_id=academic-101248-cyzanon) or use the [GitHub Student Developer Pack — GitHub Education](https://aka.ms/Copilot4Students) program.
+
+## Preparing the scenario
+
+### Create a new branch
+
+First, you will need to create a new branch in your GitHub repository and follow some configuration steps. To do this, run the following commands in the Visual Studio Code terminal in Codespaces:
+
+```bash
+  git checkout -b portal-deploy
+```
+
+### Create a copy and rename
+
+Create a copy of the `portal` folder and rename it to `portal-deploy` This duplication is necessary so that we can deploy the portal scenario separately from other parts of the project, such as the `blog` and `api`.
+
+```bash
+  cp -r packages/portal packages/portal-deploy
+```
+
+With the `portal-deploy` folder created, access the file `packages/portal-deploy/package.json` and change the `name` property to `portal-deploy`.
+
+![Package.json](./images/new-portal-package-json.jpg)
+
+## Navigate and delete existing files
+
+Now, go back to the terminal, as we will run some routines with basic Linux commands and configure the project deployment with the Azure Static Web Apps CLI.
+
+```bash
+  cd packages/portal-deploy
+```
+
+We need to delete the `swa-cli.config.json` file. To do this, we will use the linux command `rm -rf`. The -r is used to delete folders and the -f is used to force deletion.
+
+**Remove the swa-cli.config.json file:**
+
+```bash
+  rm -rf swa-cli.config.json
+```
+
+## Azure Static Web Apps (SWA) CLI
+
+With the initial settings completed, you will need to initialize Azure Static Web Apps so that we can deploy the `portal` to Azure.
+
+To do this, use the terminal to navigate to the root of the Contoso Real Estate project by running the following command:
+
+```bash
+  cd ../..
+```
+
+**Initialize Azure Static Web Apps**
+
+```bash
+  swa init
+```
+
+The SWA CLI will identify the existing projects in Contoso Real Estate and you should choose the `portal-deploy`. Check if the project name is correct and press `y` to confirm.
+
+![Visual Studio Code Terminal in Codespaces](./images/swa-init.gif)
+
+A `swa-cli.config.json` file will be generated and will have the following information:
+
+```json
+  {
+    "$schema": "https://aka.ms/azure/static-web-apps-cli/schema",
+    "configurations": {
+      "contoso-real-estate": {
+        "appLocation": "packages/portal-deploy",
+        "apiLocation": "packages/api",
+        "outputLocation": "dist/contoso-app",
+        "apiLanguage": "node",
+        "apiVersion": "16",
+        "appBuildCommand": "npm run build",
+        "apiBuildCommand": "npm run build --if-present",
+        "run": "npm start",
+        "appDevserverUrl": "http://localhost:4200"
+      }
+    }
+  }
+```
+
+In the previous exercise, we explained how the communication between the backend and the frontend works and how the `swa-cli.config.json` file is generated. In this exercise, the values of the properties are different because we are deploying the `portal` project separately from the other parts of the project and we are poining to the `portal-deploy` folder.
+
+**Execution test**
+
+```bash
+  swa start
+```
+
+During execution, a popup will open in the lower right corner of Visual Studio Code. Click on the `Ports` tab and check if port `4280` is open. If it is, click the `Open Browser` button so you can view the portal.
+
+![Ports](./images/ports-executing-new-deploy.gif)
+
+
+### Creating the artifacts
+
+Artifacts are the files that will be sent to Azure Static Web Apps. Artifacts are static files, such as HTML, CSS, JavaScript, and images, that are generated by the build process. All artifacts generated by the SWA CLI are stored in the `dist/contoso-app` folder. To generate the `portal` artifacts, run the following command:
+
+```bash
+  swa build
+```
+
+### Configuring GitHub Actions
+
+Now that we already have the generated artifacts, we need to configure GitHub Actions so that the `portal-deploy` is published on Azure Static Web Apps.
+
+To do this, access the Azure portal and create a new Azure Static Web Apps following the steps below:
+
+1. Access the Azure portal and click the `Create a resource` button.
+2. In the search bar, type `Static Web Apps` and click on the first result.
+3. Click the `Create` button.
+4. On the "Create Static Web App" page, fill in the following information:
+    - ***Subscription***: Select your Azure subscription.
+    - ***Resource Group***: Click the `Create new` button and type the name `contoso-real-estate`.
+    - ***Name***: Type the name `contoso-real-estate-portal-deploy`.
+    - ***Plan type***: Select the `Free` option.
+    - ***Region***: Select the region closest to you.
+    - ***Source***: Select the `GitHub` option. You will need to log in with your GitHub account so that Azure can access your repositories.
+    - ***Organization***: Select your GitHub organization.
+    - ***Repository***: Select the `contoso-real-estate` repository.
+    - ***Branch***: Select the `portal-deploy` branch.
+    - ***Build Presets***: Select the `Angular` option.
+    - ***App location***: Type the path `packages/portal-deploy`.
+    - ***Api location***: Type the path `packages/api`.
+    - ***Output location***: Type the path `dist/contoso-app`.
+5. Click the `Review + create` button.
+6. Click the `Create` button.
+
+Access your repository on GitHub and click on the `Actions` tab. You will see that GitHub Actions has already created a workflow called `Azure Static Web Apps CI/CD`, and it will be in progress.
+
+The steps performed on the Azure portal during the creation of Azure Static Web Apps have created a new file in the `.github/workflows` folder. This file is responsible for deploying the `portal-deploy` to Azure Static Web Apps. You can follow the progress of the deploy in GitHub Actions or in Azure Static Web Apps.
+
+![GitHub Actions Workflow](./images/github-actions-workflow.jpg)
+
+With the execution completed, access the link generated by Azure Static Web Apps. You will see the portal running on Azure.
+
+![Azure Portal](./images/azure-portal-swa-portal.png)
+
+## Congratulations
+You have successfully deployed the `portal` on Azure Static Web Apps. 🎉

devops-devtools/contoso-real-estate/event-organization/README.md

@@ -0,0 +1,38 @@
+# Event Guide
+
+A quick guide for community leaders, with tips on speaker sourcing, event promotion, and more.
+
+## Start organizing your event
+
+### Basic definition:
+- Type of content: presentations or workshop
+- Ideal format for your community: online, hybrid or in-person
+- Date and time
+- Duration: 2-3 hours
+     - If you opt for an online event, consider breaking the event into 30-45 minute sessions.
+     - For in-person event, consider a 15-minute break for participants to network.
+- Theme: all events should be related to the **Contoso Real Estate** project and its content packs. You can choose to focus on one or more themes from the project's content pack.
+- Prerequisites: If you decide host an event with a workshop, consider the prerequisites for your attendees. For example, if you are going to host a workshop on Azure Functions, you can ask your attendees to create an Azure account before the event.
+
+### Promotion
+- Use our templates to create assets and promote your event. In the [Creative](/Creative) folder, you will find the downloadable templates:
+     - Event cover for Meetup
+     - Card for speakers
+     - Thumbnail for YouTube
+     - Power Point template
+- Create the registration link for your event, using [Meetup](https://www.meetup.com/pt-BR/), Microsoft Forms or another platform of your choice.
+- Remember to include a code of conduct in your event. A CoC is important to ensure that all participants feel safe and comfortable during the event. Be inspired by the [Reactor Code of Conduct](https://developer.microsoft.com/en-us/reactor/CodeOfConduct/).
+- Connect with local communities, universities, schools, to promote registration for your event.
+- 5 and 2 days prior to the event, send a reminder email to your attendees list and encourage them to share the event with their friends and co-workers.
+- On the day of the event, send a final reminder with link to access the online event or tips to find the location (if in-person).
+
+### Finding speakers
+If you want to find speakers for your event, you can search for members of Microsoft's community programs:
+
+- [Find an MVP (Most Valuable Professional)](https://mvp.microsoft.com/pt-br/MvpSearch)
+- [Find an MSLA (Microsoft Learn Student Ambassador)](https://studentambassadors.microsoft.com/pt-BR/search?target=Profile)
+
+Tip: in your invite, talk about the **Enterprise-grade Reference Architecture for JavaScript** project and share the content you want the speaker to present.
+
+## Content
+In this repository you will find presentations and workshops that you can use in your event. Navigate to the [content](/content) folder to find the content packs for each project.