---
# System prepended metadata

title: MedDict VinUni Maintainer Manual

---

# MedDict-VinUni Maintainer Manual

[TOC]

# Description

This manual is acting as the maintainer guideline for future maintainers and/or developers of the application MedDict-VinUni, including:

+ The frontend & backend of [MedDict-VinUni](https://meddict-vinuni.com)
+ The plugin [MedDict-Highlighter](https://github.com/linhledieu/MedDict-highlighter)
+ The associated Google Apps Script functions in [MedDict VinUni Project spreadsheet](https://docs.google.com/spreadsheets/d/1bq5Bj2p9TUCnezpkiDKtJOKD5V87cWhkZcsN-XmFbx4/edit?usp=sharing)

Although we have tried to document as much as possible, there might be a lot of errors, misunderstanding or other technical problems when refers to the docs. Therefore, we welcome all maintainers & developers of the project to contact us:

+ **Frontend Lead Developer**: [Mr. Nguyen Tung Lam](mailto:21lam.nt@vinuni.edu.vn)
+ **Backend Lead Developer**: [Mr. Nguyen Tuan Anh](mailto:21anh.nt@vinuni.edu.vn)
+ **MedDict-Highlighter's Developers**: [Ms. Le Dieu Linh](mailto:21linh.ld@vinuni.edu.vn)
+ **Project Manager**: [Mr. Nguyen Nhat Minh](mailto:21minh.nn2@vinuni.edu.vn)

# Requirement Analysis & Specification

Please refer to our report in [here](https://docs.google.com/document/d/1uGaYGFbZ70wfFL5K82F_iof82ASRNB3Y/edit?usp=drive_link&ouid=103232476217020077352&rtpof=true&sd=true)

# System Design

As mentioned above, our application is an eco-system of three components: Frontend, Backend and the Apps Script from Google.

The overall design of the application can be viewed from this image:

![image](https://hackmd.io/_uploads/S1Jwv_9Fa.png)

Note that, the website of MedDict VinUni & Backend are hosted in different Docker containers. 

More in-depth design of the application can be found in [this report](https://docs.google.com/document/d/1LUdJpwGSzS7OFeZ3gyDhnLIeiS6FfV57/edit?usp=sharing&ouid=103232476217020077352&rtpof=true&sd=true)

# Deployment 

## Prerequisite

Make sure you are having either [Docker Desktop](https://www.docker.com/products/docker-desktop/) or [Docker Engine](https://docs.docker.com/engine/) on your device/server. We highly recommend you use a Linux Distro to host the application. 

## Installation 

### MedDict Website & Backend API 

1. Clone the project 

```bash!
git clone https://github.com/tunglambg131003/COMP2030_Meddict
cd COMP2030_Meddict
```

2. Create a `.env` file under the repository. You can take the `.env_sample` in the repository as example. 
    We highly recommend using `secret` modules of Python or any equivalent password/token randomizers to act as the password of users and API key of the app.
    
```python
>>> import secrets
>>> secrets.token_urlsafe(32) # use your wanted length here 
'kj8ynv0gw-FZL4ti-pdeecPwOE0zJ2X_47wRsG5TvTs'
>>>        
```

3. Create a `mongo-init.js` file to initialize the database. You can take the `sample-mongo-init.js` in the repository as example. 
    **Notes**: The usage of `users` database is **deprecated**. You can safely remove the lines related to this database in `sample-mongo-init.js` file. 
    
4. Run the following command:
```Bash
docker compose up -d build
```
5. You are done! Access the service at `localhost` via your web browser if you are installing in local machine, or the server IP address/domain name if you are deploying it on a cloud instance.


### MedDict Apps Script plugin

0. You should install [`clasp`](https://codelabs.developers.google.com/codelabs/clasp/#0) - The CLI tool for Google Apps Script.
1. `Optional`: Create a new Google Spreadsheet, in which you follow the format of the original MedDict VinUni Project template.
2. Open the Google Spreadsheet, and go to `Extensions` -> `Apps Script`. Collect the project ID of the project. `https://script.google.com/u/0/home/projects/<YOUR_PROJECT_ID_HERE>/`
3. Run the following command 
```bash
clasp login # login into your SpreadSheet Account
clasp clone $PROJECT_ID
```
4. Copy files from `apps_script` folder. You can follow [this tutorial](https://developers.google.com/apps-script/guides/typescript) for using TypeScript during your development.
5. Create a `MedDict_Config.js` or `.ts` file with the following content:
```javascript!
var ALLOWED_USERS = [
     // List of your whitelist admin
];
var API_KEY = "API_KEY"; // Your API_KEY from .env file
```
5.Run the following command to push your changes to the Google Spreadsheet

```bash!
clasp push
```

6. You are done! You can now automate your editing process with the Google Spreadsheet.

## Development 

Currently, the code is **UNDER DEVELOPMENT**. The following instructions are for developers in the project.

### MongoDB data

Currently, the data for MongoDB is not inserted automatically. You need to insert the data manually by:

1. Access the MongoDB container by running the following command:
```bash
docker exec -it mongodb bash
```

2. In the MongoDB container, run the following command: 
```bash
mongoimport --host mongodb --db MedDict --collection dictionary --authenticationDatabase admin --username $MONGO_INITDB_ROOT_USERNAME --password $MONGO_INITDB_ROOT_PASSWORD --type json --file /data/database.json --jsonArray
```

The current (04 Feb 2024) data is located in this folder. 

#### ALTERNATIVE

The current development code is using another "pseudo" domain: `meddict.com` for the website and `api.meddict.com` for the API endpoints. You can do so by adding the following lines to your `/etc/hosts` file:

```
127.0.0.1       localhost
127.0.0.1       api.meddict.com 
127.0.0.1       meddict.com
::1             localhost
```

# Documentation

The Backend API documentation is available at: 
+ Product API: https://api.meddict-vinuni.com/docs
+ Detailed API: https://bump.sh/h114mx001/doc/meddict-vinuni

# Final user interface design & Developer workflow

Our developer notes & guideline of the installation is mentioned in our project [README](https://github.com/tunglambg131003/COMP2030_Meddict).

Also, a demo of usage of the plugins is available at this [YouTube video](https://youtu.be/D39WHLtth_8)

# FAQ 

##### I can't build the project after cloning? 

You may have a problem with Docker and/or haven't config the `.env` and `mongo-init.js` file as shown in the [Deployment](#Deployment) part. Review it one more time. 

##### I can't find any illustration?! 

Please review the part of [MongoDB](#MongoDB-data) for our latest backup version. It should contain the images & database init file for you. Place them at the `data/` folder. 

##### I can't access the webpage after build? 

As mentioned, we used a pseudo URL `api.meddict.com` as our development URL. You can visit the [Development](#Development) section for config your own development environment. 