Skip to content

Commit a6127a7

Browse files
cyzcyz
authored
Add files via upload
1 parent 48c78ce commit a6127a7

File tree

9 files changed

+403
-0
lines changed

9 files changed

+403
-0
lines changed

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# 🚀 Prepare for the challenge
2+
3+
You will use GitHub Codespaces to work on the Contoso Real Estate `portal` project.
4+
5+
## What is GitHub Codespaces?
6+
7+
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.
8+
9+
Development containers, or dev containers, are Docker containers that are specifically configured to provide a complete development environment.
10+
11+
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.
12+
13+
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:
14+
15+
![Dev Container Diagram](./images/dev-container.png)
16+
17+
The Contoso Real Estate project is optimized for use with GitHub Codespaces, a cloud-hosted development environment from GitHub.
18+
19+
20+
## Getting started
21+
22+
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/).
23+
24+
2. Activate the [GitHub Codespaces](https://docs.github.com/codespaces/) service on your GitHub account. Codespaces offers 60 hours of free usage per month.
25+
26+
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.
27+
28+
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.
29+
30+
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.
31+
32+
---
33+
34+
[**➡️ Exercise 1: Analyzing the portal project**](./01-analyzing-portal.md)

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

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# 🔎 Exercise 1: Analyzing the `portal` project
2+
3+
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.
4+
5+
<img src="./images/composable-architecture-example.png" title="Composable Architecture Diagram" height="450" />
6+
7+
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.
8+
9+
**Advantages of using composable architecture:**
10+
11+
- **Reusability**: components can be reused in different parts of the application.
12+
- **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.
13+
- **Maintainability**: the application can be maintained more easily as each component is responsible for a specific functionality.
14+
15+
## Project architecture
16+
17+
The Contoso Real Estate project is composed of three main parts:
18+
19+
- `portal`: is the main project, where it contains the home page and the components that will be used on all pages.
20+
- `blog`: is the project that contains the real estate blog. In this project, `Strapi` is used as a CMS to manage blog posts.
21+
- `api`: is the project that contains the APIs that will be used in the `portal` project.
22+
23+
![Contoso Real Estate Diagram](./images/e2e-full-horizontal.drawio.png)
24+
25+
### The `portal` components
26+
27+
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.
28+
29+
Accessing the `packages/portal/src/app` folder, you will see the components that make up the `portal`:
30+
31+
- `app`: main component of the application, responsible for rendering the other components.
32+
- `about`: about page
33+
- `authentication`: login page (authentication)
34+
- `checkoutpage`: checkout page
35+
- `homepage`: home page
36+
- `profile`: user profile page
37+
- `rentalpage`: rental page
38+
- `searchpage`: search page
39+
- `shared`: folder that contains the components of universal use in the application, such as buttons, inputs, etc.
40+
41+
![Componentes](./images/gif-arquitetura-portal.gif)
42+
43+
### Environment variables
44+
45+
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.
46+
47+
For example, observe the excerpt below:
48+
49+
<details><summary><b>environments/environmet.ts</b></summary>
50+
<br/>
51+
52+
```ts
53+
export const environment = {
54+
production: false,
55+
blogUrl: 'http://localhost:3000',
56+
isCodespaces: process.env["CODESPACE_NAME"] ? true : false,
57+
strapiGraphQlUriInCodespace: `https://${process.env["CODESPACE_NAME"]}-1337.${process.env["GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN"]}/graphql`,
58+
strapiGraphQlUriFallback: 'http://localhost:1337/graphql'
59+
};
60+
```
61+
62+
</details>
63+
<br/>
64+
65+
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`.
66+
67+
In the next exercise, you will learn how to run the `portal` project using the Azure Static Web Apps CLI.
68+
69+
---
70+
71+
[**➡️ 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‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# 💻 Exercise 2: Working with Azure Static Web App CLI
2+
3+
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.
4+
5+
## What is Azure Static Web App CLI?
6+
7+
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.
8+
9+
## How does the communication between frontend and backend work?
10+
11+
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`.
12+
13+
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**.
14+
15+
```bash
16+
swa init
17+
```
18+
19+
Please see the step-by-step creation of the file in the image below:
20+
21+
![SWA init Contoso](./images/swa-init-contoso.gif)
22+
23+
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:
24+
25+
<details><summary><b>packages/portal/swa-cli.config.json</b></summary>
26+
<br/>
27+
28+
```json
29+
{
30+
"$schema": "https://aka.ms/azure/static-web-apps-cli/schema",
31+
"configurations": {
32+
"contoso-real-estate": {
33+
"appLocation": ".",
34+
"apiLocation": "../api",
35+
"outputLocation": "dist/contoso-app",
36+
"appBuildCommand": "npm run build",
37+
"apiBuildCommand": "npm run build",
38+
"run": "npm start",
39+
"appDevserverUrl": "http://localhost:4200",
40+
"apiDevserverUrl": "http://127.0.01:7071"
41+
}
42+
}
43+
}
44+
```
45+
</details>
46+
<br/>
47+
48+
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.
49+
50+
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.
51+
52+
## How to run the `portal` project?
53+
54+
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.
55+
56+
> 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).
57+
58+
To run the project in your Visual Studio Code in Codespaces, follow the steps below:
59+
60+
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:
61+
- 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.
62+
63+
> _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._
64+
65+
2. Once all the development servers have started, the following URLs will be available:
66+
67+
| Application | URL | Port |
68+
| -------------- | -------------------------------------------------------- | ---- |
69+
| Portal | https://YOUR-REPO-4280.preview.app.github.dev:4280 | 4280 |
70+
| Blog | https://YOUR-REPO-3000.preview.app.github.dev:3000 | 3000 |
71+
| Strapi CMS | https://YOUR-REPO-1337.preview.app.github.dev:1337/admin | 1337 |
72+
| Serverless API | https://YOUR-REPO-7071.preview.app.github.dev:7071/api/ | 7071 |
73+
| Stripe API | https://YOUR-REPO-4242.preview.app.github.dev:4242 | 4242 |
74+
75+
> _Note: The URLs above are just examples. The URLs will be different for your fork. The ports, however, will be the same._
76+
77+
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.
78+
79+
![Terminal Ports](./images/terminal-ports.png)
80+
81+
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.
82+
83+
The example below shows the portal home page with the sample data.
84+
85+
![Portal Home Page](./images/gif-portal-contoso.gif)
86+
87+
### Understanding the `Portal` project execution
88+
89+
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.**
90+
91+
**How can we check this?**
92+
93+
Open the `package.json` file at the root of the Contoso project and observe the scripts below:
94+
95+
<details><summary><b>packages/portal/package.json</b></summary><br/>
96+
97+
```json
98+
"scripts": {
99+
"start": "concurrently npm:start:* --kill-others",
100+
"start:services": "docker compose up",
101+
"start:api": "npm run start --workspace=api",
102+
"start:website": "npm run start:swa --workspace=portal",
103+
"test": "npm run test -ws --if-present",
104+
"build": "npm run build -ws --if-present",
105+
"format": "prettier --write .",
106+
"format:check": "prettier --check .",
107+
"lint": "npm run lint -ws --if-present",
108+
"lint:fix": "npm run lint:fix -ws --if-present",
109+
"clean": "rimraf \"packages/**/*.tsbuildinfo\"",
110+
"clean:install": "rimraf \"packages/**/node_modules\" \"node_modules\" && npm install"
111+
}
112+
```
113+
</details>
114+
<br/>
115+
116+
Checking the scripts:
117+
118+
**Docker compose**
119+
120+
```json
121+
"start:services": "docker compose up"
122+
```
123+
124+
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.
125+
126+
**API**
127+
```json
128+
"start:api": "npm run start --workspace=api"
129+
```
130+
131+
Responsible for running the `API` project.
132+
133+
**Portal**
134+
```json
135+
"start:website": "npm run start:swa --workspace=portal"
136+
```
137+
138+
Responsible for running the `portal` project.
139+
140+
#### Understanding the Heart of the SWA CLI: Reverse Proxy
141+
142+
This is the heart of the SWA CLI. It intercepts and forwards HTTP requests to the right components based on purpose:
143+
144+
- `/.auth/**` requests => forwarded to the Auth emulator server.
145+
- `/api/**` requests => forwarded to the API backend (if configured).
146+
- `/**` => all other requests forwarded to the static assets content server.
147+
148+
![Azure Static Web Apps CLI - Reserve Proxy](./images/swa-cli-ports.png)
149+
150+
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).
151+
152+
In the next exercise, you will learn how to deploy the `portal` project on Azure Static Web Apps.
153+
154+
---
155+
156+
[**➡️ Exercise 3: Deploy on Azure Static Web App**](./03-exercise-portal-deploy.md)

0 commit comments

Comments
 (0)