Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• backend/package.json
• backend/src/server.js
• frontend/package.json
• frontend/src/App.js

This guide provides instructions for setting up and running the CDIO4 project, a full-stack application using the REMN (React, Express, MongoDB, Node.js) stack. The project consists of a React frontend for the user interface and an Express.js backend server that provides APIs and connects to a MongoDB database.

This document covers the system requirements, project structure, and step-by-step installation process for running the application in a local development environment. The instructions are derived from the project's configuration and documentation files.

System Requirements

Before starting, ensure your development environment meets the following requirements.

Component	Version/Requirement	Source(s)
Node.js	>= 16.0.0	[README.md:52](https://github.com/HoangHao1404/CDIO4/blob/HEAD/README.md#L52), [package.json:30](https://github.com/HoangHao1404/CDIO4/blob/HEAD/package.json#L30), [backend/package.json:32](https://github.com/HoangHao1404/CDIO4/blob/HEAD/backend/package.json#L32)
npm	>= 8.0.0 (or yarn)	[README.md:53](https://github.com/HoangHao1404/CDIO4/blob/HEAD/README.md#L53), [package.json:31](https://github.com/HoangHao1404/CDIO4/blob/HEAD/package.json#L31)
MongoDB	>= 5.0 (local instance or a cloud service like Atlas)	[README.md:54](https://github.com/HoangHao1404/CDIO4/blob/HEAD/README.md#L54)
Git	Required for cloning the repository	[README.md:55](https://github.com/HoangHao1404/CDIO4/blob/HEAD/README.md#L55)

Project Architecture

The project is a monorepo containing two main sub-projects: frontend and backend.

• frontend/: A React application created with react-scripts. It serves the user interface and communicates with the backend via API calls.
• backend/: An Express.js server that handles business logic, serves API endpoints, and interacts with the MongoDB database.

The diagram below illustrates the high-level structure of the repository.

This diagram shows the main directories within the project repository.
Sources: README.md:16-47

Installation and Setup

Follow these steps to get the application running on your local machine.

1. Clone the Repository

First, clone the project from GitHub to your local machine.

git clone https://github.com/HoangHao1404/CDIO4.git
cd CDIO4

Sources: README.md:59-62

2. Backend Setup

The backend server requires a connection to a MongoDB database and some environment variables.

1. Navigate to the backend directory:

   cd backend
   

2. Install dependencies:

   npm install
   

   This command installs packages like express, mongoose, cors, and dotenv listed in backend/package.json.
   Sources: backend/package.json:17-27, README.md:65

3. Configure Environment Variables:
   The backend server is configured using a .env file. Create a .env file in the backend directory by copying the example file.

   cp .env.example .env
   

   You must then edit the .env file to provide the necessary values.
   Sources: README.md:67, backend/src/server.js:7

   Variable	Description -
   MONGODB_URI	The connection string for your MongoDB database. - [backend/src/server.js:18](https://github.com/HoangHao1404/CDIO4/blob/HEAD/backend/src/server.js#L18) -

• BACKEND_PORT | The port on which the backend server will run. Defaults to 5000. Note: The frontend proxy is configured for port 5001, so it's recommended to set this to 5001. | [backend/src/server.js:10](https://github.com/HoangHao1404/CDIO4/blob/HEAD/backend/src/server.js#L10), [frontend/package.json:30](https://github.com/HoangHao1404/CDIO4/blob/HEAD/frontend/package.json#L30) - FRONTEND_URL | The URL of the running frontend application, used for CORS configuration. e.g., http://localhost:3000. - [backend/src/server.js:40](https://github.com/HoangHao1404/CDIO4/blob/HEAD/backend/src/server.js#L40) -

1. Start the backend server:

   npm run dev
   

   This script uses nodemon to start the server, which will automatically restart upon file changes. The server will be running at the URL specified by your BACKEND_PORT, e.g., http://localhost:5001.
   Sources: backend/package.json:8, backend/src/server.js:93

3. Frontend Setup

The frontend is a React application.

1. Navigate to the frontend directory:
   From the project root:

   cd frontend
   

2. Install dependencies:

   npm install
   

   This installs React, React Router, and other libraries defined in frontend/package.json.
   Sources: frontend/package.json:5-13, README.md:72

3. Start the frontend development server:

   npm start
   

   This will open the application in your default browser, typically at http://localhost:3000.
   Sources: frontend/package.json:16, README.md:73

Frontend to Backend Communication

The frontend application uses a proxy to forward API requests to the backend server during development. This is configured in frontend/package.json.

"proxy": "http://localhost:5001"

This means any unrecognized request from the React app (e.g., /api/users) will be forwarded to http://localhost:5001/api/users. Ensure your BACKEND_PORT environment variable matches the port used in this proxy setting.

Sources: frontend/package.json:30

The following diagram shows the data flow in the local development environment.

4. Concurrent Execution (Recommended)

The root package.json provides a convenient script to run both the frontend and backend servers concurrently with a single command.

1. Navigate to the project root directory.
2. Install root dependencies (if you haven't already):

   npm install
   

   This installs concurrently.
   Sources: package.json:27
3. Run the development script:

   npm run dev
   

   This command executes concurrently "npm run server" "npm run client", which in turn runs npm run dev in the backend directory and npm start in the frontend directory.
   Sources: package.json:7-9

Available NPM Scripts

The project includes several NPM scripts to streamline development tasks.

Location	Script	Description -
Root	dev	Runs both backend and frontend servers concurrently. - [package.json:7](https://github.com/HoangHao1404/CDIO4/blob/HEAD/package.json#L7) -
	install-all	Installs dependencies for the root, backend, and frontend. - [package.json:12](https://github.com/HoangHao1404/CDIO4/blob/HEAD/package.json#L12) -
Backend	start	Runs the backend server using node (for production). - [backend/package.json:7](https://github.com/HoangHao1404/CDIO4/blob/HEAD/backend/package.json#L7) -
	dev	Runs the backend server using nodemon (for development). - [backend/package.json:8](https://github.com/HoangHao1404/CDIO4/blob/HEAD/backend/package.json#L8) -
Frontend	start	Starts the React development server. - [frontend/package.json:16](https://github.com/HoangHao1404/CDIO4/blob/HEAD/frontend/package.json#L16) -
	build	Builds the frontend app for production. - [frontend/package.json:17](https://github.com/HoangHao1404/CDIO4/blob/HEAD/frontend/package.json#L17) -

Sources: README.md:92-104