Skip to content

Commit 44c8016

Browse files
guanquannguanquann
committed
Update readme
1 parent 38e964b commit 44c8016

File tree

4 files changed

+54
-298
lines changed

4 files changed

+54
-298
lines changed

‎backend/question-service/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,14 @@
11
# Question Service
2+
3+
4+
## Running Question Service
5+
6+
1. Open Command Line/Terminal and navigate into the `question-service` directory.
7+
8+
2. Run the command: `npm install`. This will install all the necessary dependencies.
9+
10+
3. Run the command `npm start` to start the Question Service in production mode, or use `npm run dev` for development mode, which includes features like automatic server restart when you make code changes.
11+
12+
4. To view Question Service documentation, go to http://localhost:3001/docs.
13+
14+
5. Using applications like Postman, you can interact with the Question Service on port 3000. If you wish to change this, please update the `.env` file.

‎backend/user-service/MongoDBSetup.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Setting up MongoDB Instance for User Service
1+
# Setting up MongoDB Instance
22

33
1. Visit the MongoDB Atlas Site [https://www.mongodb.com/atlas](https://www.mongodb.com/atlas) and click on "Try Free"
44

@@ -33,11 +33,10 @@
3333

3434
![alt text](./GuideAssets/Selection4.png)
3535

36-
6. You will be prompted to set up Security for the database by providing `Username and Password`. Select that option and enter `Username` and `Password`. Please keep this safe as it will be used in User Service later on.
3736

3837
![alt text](./GuideAssets/Security.png)
3938

40-
7. Next, click on `Add my Current IP Address`. This will whiteliste your IP address and allow you to connect to the MongoDB Database.
39+
7. Next, click on `Add my Current IP Address`. This will whitelist your IP address and allow you to connect to the MongoDB Database.
4140

4241
![alt text](./GuideAssets/Network.png)
4342

‎backend/user-service/README.md‎

Lines changed: 33 additions & 250 deletions
Original file line numberDiff line numberDiff line change
@@ -1,286 +1,69 @@
11
# User Service Guide
22

3-
## Setting-up
3+
## Setting-up MongoDB
44

55
> :notebook: If you are familiar to MongoDB and wish to use a local instance, please feel free to do so. This guide utilizes MongoDB Cloud Services.
66
7-
1. Set up a MongoDB Shared Cluster by following the steps in this [Guide](./MongoDBSetup.md).
7+
1. Set up a MongoDB Shared Cluster by following the steps in this [Guide](MongoDBSetup.md).
88

99
2. After setting up, go to the Database Deployment Page. You would see a list of the Databases you have set up. Select `Connect` on the cluster you just created earlier on for User Service.
1010

11-
![alt text](./GuideAssets/ConnectCluster.png)
11+
![alt text](GuideAssets/ConnectCluster.png)
1212

1313
3. Select the `Drivers` option, as we have to link to a Node.js App (User Service).
1414

15-
![alt text](./GuideAssets/DriverSelection.png)
15+
![alt text](GuideAssets/DriverSelection.png)
1616

1717
4. Select `Node.js` in the `Driver` pull-down menu, and copy the connection string.
1818

1919
Notice, you may see `<password>` in this connection string. We will be replacing this with the admin account password that we created earlier on when setting up the Shared Cluster.
2020

21-
![alt text](./GuideAssets/ConnectionString.png)
21+
![alt text](GuideAssets/ConnectionString.png)
2222

2323
5. In the `user-service` directory, create a copy of the `.env.sample` file and name it `.env`.
2424

25-
6. Update the `DB_CLOUD_URI` of the `.env` file, and paste the string we copied earlier in step 4. Also remember to replace the `<password>` placeholder with the actual password.
25+
6. Update the `DB_CLOUD_URI` of the `.env` file, and paste the string we copied earlier in step 4.
2626

27-
## Running User Service
28-
29-
1. Open Command Line/Terminal and navigate into the `user-service` directory.
30-
31-
2. Run the command: `npm install`. This will install all the necessary dependencies.
32-
33-
3. If you are running the user service for the first time, run `npm run seed`, to seed the database with a default admin account. If you wish to change the default, please update the `.env` file. Alternatively, you can also edit your credentials and user profile after you have created the default account.
34-
35-
4. Run the command `npm start` to start the User Service in production mode, or use `npm run dev` for development mode, which includes features like automatic server restart when you make code changes.
36-
37-
5. Using applications like Postman, you can interact with the User Service on port 3001. If you wish to change this, please update the `.env` file.
38-
39-
## User Service API Guide
27+
## Setting-up Firebase
4028

41-
### Create User
29+
1. Go to https://console.firebase.google.com/u/0/.
4230

43-
- This endpoint allows adding a new user to the database (i.e., user registration).
31+
2. Create a project and choose a project name. Navigate to `Storage` and click on it to activate it.
4432

45-
- HTTP Method: `POST`
33+
3. Select `Start in production mode` and your preferred cloud storage region.
4634

47-
- Endpoint: http://localhost:3001/users
48-
49-
- Body
50-
51-
- Required: `firstName` (string), `lastName` (string), `username` (string), `email` (string), `password` (string)
52-
53-
```json
54-
{
55-
"firstName": "SampleFirstName",
56-
"lastName": "SampleLastName",
57-
"username": "SampleUserName",
58-
"email": "[email protected]",
59-
"password": "SecurePassword"
60-
}
35+
4. After Storage is created, go to `Rules` section and set rule to:
6136
```
62-
63-
- Responses:
64-
65-
| Response Code | Explanation |
66-
| --------------------------- | ----------------------------------------------------- |
67-
| 201 (Created) | User created successfully, created user data returned |
68-
| 400 (Bad Request) | Missing fields |
69-
| 409 (Conflict) | Duplicate username or email encountered |
70-
| 500 (Internal Server Error) | Database or server error |
71-
72-
### Get User
73-
74-
- This endpoint allows retrieval of a single user's data from the database using the user's ID.
75-
76-
> :bulb: The user ID refers to the MongoDB Object ID, a unique identifier automatically generated by MongoDB for each document in a collection.
77-
78-
- HTTP Method: `GET`
79-
80-
- Endpoint: http://localhost:3001/users/{userId}
81-
82-
- Parameters
83-
84-
- Required: `userId` path parameter
85-
- Example: `http://localhost:3001/users/60c72b2f9b1d4c3a2e5f8b4c`
86-
87-
- <a name="auth-header">Headers</a>
88-
89-
- Required: `Authorization: Bearer <JWT_ACCESS_TOKEN>`
90-
91-
- Explanation: This endpoint requires the client to include a JWT (JSON Web Token) in the HTTP request header for authentication and authorization. This token is generated during the authentication process (i.e., login) and contains information about the user's identity. The server verifies this token to ensure that the client is authorized to access the data.
92-
93-
- Auth Rules:
94-
95-
- Admin users: Can retrieve any user's data. The server verifies the user associated with the JWT token is an admin user and allows access to the requested user's data.
96-
- Non-admin users: Can only retrieve their own data. The server checks if the user ID in the request URL matches the ID of the user associated with the JWT token. If it matches, the server returns the user's own data.
97-
98-
- Responses:
99-
100-
| Response Code | Explanation |
101-
| --------------------------- | -------------------------------------------------------- |
102-
| 200 (OK) | Success, user data returned |
103-
| 401 (Unauthorized) | Access denied due to missing/invalid/expired JWT |
104-
| 403 (Forbidden) | Access denied for non-admin users accessing others' data |
105-
| 404 (Not Found) | User with the specified ID not found |
106-
| 500 (Internal Server Error) | Database or server error |
107-
108-
### Get All Users
109-
110-
- This endpoint allows retrieval of all users' data from the database.
111-
- HTTP Method: `GET`
112-
- Endpoint: http://localhost:3001/users
113-
- Headers
114-
115-
- Required: `Authorization: Bearer <JWT_ACCESS_TOKEN>`
116-
- Auth Rules:
117-
118-
- Admin users: Can retrieve all users' data. The server verifies the user associated with the JWT token is an admin user and allows access to all users' data.
119-
- Non-admin users: Not allowed access.
120-
121-
- Responses:
122-
123-
| Response Code | Explanation |
124-
| --------------------------- | ------------------------------------------------ |
125-
| 200 (OK) | Success, all user data returned |
126-
| 401 (Unauthorized) | Access denied due to missing/invalid/expired JWT |
127-
| 403 (Forbidden) | Access denied for non-admin users |
128-
| 500 (Internal Server Error) | Database or server error |
129-
130-
### Update User
131-
132-
- This endpoint allows updating a user and their related data in the database using the user's ID.
133-
134-
- HTTP Method: `PATCH`
135-
136-
- Endpoint: http://localhost:3001/users/{userId}
137-
138-
- Parameters
139-
140-
- Required: `userId` path parameter
141-
142-
- Body
143-
144-
- At least one of the following fields is required: `username` (string), `email` (string), `password` (string)
145-
146-
```json
147-
{
148-
"username": "SampleUserName",
149-
"email": "[email protected]",
150-
"password": "SecurePassword"
151-
}
152-
```
153-
154-
- Headers
155-
156-
- Required: `Authorization: Bearer <JWT_ACCESS_TOKEN>`
157-
- Auth Rules:
158-
159-
- Admin users: Can update any user's data. The server verifies the user associated with the JWT token is an admin user and allows the update of requested user's data.
160-
- Non-admin users: Can only update their own data. The server checks if the user ID in the request URL matches the ID of the user associated with the JWT token. If it matches, the server updates the user's own data.
161-
162-
- Responses:
163-
164-
| Response Code | Explanation |
165-
| --------------------------- | ------------------------------------------------------- |
166-
| 200 (OK) | User updated successfully, updated user data returned |
167-
| 400 (Bad Request) | Missing fields |
168-
| 401 (Unauthorized) | Access denied due to missing/invalid/expired JWT |
169-
| 403 (Forbidden) | Access denied for non-admin users updating others' data |
170-
| 404 (Not Found) | User with the specified ID not found |
171-
| 409 (Conflict) | Duplicate username or email encountered |
172-
| 500 (Internal Server Error) | Database or server error |
173-
174-
### Update User Privilege
175-
176-
- This endpoint allows updating a user’s privilege, i.e., promoting or demoting them from admin status.
177-
178-
- HTTP Method: `PATCH`
179-
180-
- Endpoint: http://localhost:3001/users/{userId}
181-
182-
- Parameters
183-
184-
- Required: `userId` path parameter
185-
186-
- Body
187-
188-
- Required: `isAdmin` (boolean)
189-
190-
```json
191-
{
192-
"isAdmin": true
37+
rules_version = '2';
38+
service firebase.storage {
39+
match /b/{bucket}/o {
40+
match /{allPaths=**} {
41+
allow read: if true;
42+
allow write: if request.auth != null;
43+
}
44+
}
19345
}
19446
```
47+
This rule ensures that only verified users can upload images while ensuring that URLs of images are public. Remember to click `Publish` to save changes.
19548
196-
- Headers
197-
198-
- Required: `Authorization: Bearer <JWT_ACCESS_TOKEN>`
199-
- Auth Rules:
200-
201-
- Admin users: Can update any user's privilege. The server verifies the user associated with the JWT token is an admin user and allows the privilege update.
202-
- Non-admin users: Not allowed access.
203-
204-
> :bulb: You may need to manually assign admin status to the first user by directly editing the database document before using this endpoint.
205-
206-
- Responses:
49+
5. Go to `Settings`, `Project settings`, `Service accounts` and click `Generate new private key`. This will download a `.json` file, which will contain your credentials.
20750
208-
| Response Code | Explanation |
209-
| --------------------------- | --------------------------------------------------------------- |
210-
| 200 (OK) | User privilege updated successfully, updated user data returned |
211-
| 400 (Bad Request) | Missing fields |
212-
| 401 (Unauthorized) | Access denied due to missing/invalid/expired JWT |
213-
| 403 (Forbidden) | Access denied for non-admin users |
214-
| 404 (Not Found) | User with the specified ID not found |
215-
| 500 (Internal Server Error) | Database or server error |
51+
6. In `.env` of question service, replace:
52+
- `FIREBASE_PROJECT_ID` with `project_id` found in the downloaded json file.
53+
- `FIREBASE_PRIVATE_KEY` with `private_key` found in the downloaded json file.
54+
- `FIREBASE_CLIENT_EMAIL` with `client_email` found in the downloaded json file.
55+
- `FIREBASE_STORAGE_BUCKET` with the folder path of the Storage. It should look something like `gs://<appname>.appspot.com`.
21656
217-
### Delete User
218-
219-
- This endpoint allows deletion of a user and their related data from the database using the user's ID.
220-
- HTTP Method: `DELETE`
221-
- Endpoint: http://localhost:3001/users/{userId}
222-
- Parameters
223-
224-
- Required: `userId` path parameter
225-
226-
- Headers
227-
228-
- Required: `Authorization: Bearer <JWT_ACCESS_TOKEN>`
229-
230-
- Auth Rules:
231-
232-
- Admin users: Can delete any user's data. The server verifies the user associated with the JWT token is an admin user and allows the deletion of requested user's data.
233-
234-
- Non-admin users: Can only delete their own data. The server checks if the user ID in the request URL matches the ID of the user associated with the JWT token. If it matches, the server deletes the user's own data.
235-
236-
- Responses:
237-
238-
| Response Code | Explanation |
239-
| --------------------------- | ------------------------------------------------------- |
240-
| 200 (OK) | User deleted successfully |
241-
| 401 (Unauthorized) | Access denied due to missing/invalid/expired JWT |
242-
| 403 (Forbidden) | Access denied for non-admin users deleting others' data |
243-
| 404 (Not Found) | User with the specified ID not found |
244-
| 500 (Internal Server Error) | Database or server error |
245-
246-
### Login
247-
248-
- This endpoint allows a user to authenticate with an email and password and returns a JWT access token. The token is valid for 1 day and can be used subsequently to access protected resources. For example usage, refer to the [Authorization header section in the Get User endpoint](#auth-header).
249-
- HTTP Method: `POST`
250-
- Endpoint: http://localhost:3001/auth/login
251-
- Body
252-
253-
- Required: `email` (string), `password` (string)
254-
255-
```json
256-
{
257-
"email": "[email protected]",
258-
"password": "SecurePassword"
259-
}
260-
```
261-
262-
- Responses:
57+
## Running User Service
26358
264-
| Response Code | Explanation |
265-
| --------------------------- | -------------------------------------------------- |
266-
| 200 (OK) | Login successful, JWT token and user data returned |
267-
| 400 (Bad Request) | Missing fields |
268-
| 401 (Unauthorized) | Incorrect email or password |
269-
| 500 (Internal Server Error) | Database or server error |
59+
1. Open Command Line/Terminal and navigate into the `user-service` directory.
27060
271-
### Verify Token
61+
2. Run the command: `npm install`. This will install all the necessary dependencies.
27262
273-
- This endpoint allows one to verify a JWT access token to authenticate and retrieve the user's data associated with the token.
274-
- HTTP Method: `GET`
275-
- Endpoint: http://localhost:3001/auth/verify-token
276-
- Headers
63+
3. If you are running the user service for the first time, run `npm run seed`, to seed the database with a default admin account. If you wish to change the default, please update the `.env` file. Alternatively, you can also edit your credentials and user profile after you have created the default account.
27764
278-
- Required: `Authorization: Bearer <JWT_ACCESS_TOKEN>`
65+
4. Run the command `npm start` to start the User Service in production mode, or use `npm run dev` for development mode, which includes features like automatic server restart when you make code changes.
27966
280-
- Responses:
67+
5. To view User Service documentation, go to http://localhost:3001/docs.
28168
282-
| Response Code | Explanation |
283-
| --------------------------- | -------------------------------------------------- |
284-
| 200 (OK) | Token verified, authenticated user's data returned |
285-
| 401 (Unauthorized) | Missing/invalid/expired JWT |
286-
| 500 (Internal Server Error) | Database or server error |
69+
6. Using applications like Postman, you can interact with the User Service on port 3001. If you wish to change this, please update the `.env` file.

0 commit comments

Comments
 (0)