# SUPERB website maintenance

看不懂任何東西就先問 ChatGPT-4 (3.5 比較笨)，還是看不懂再問[書文哥](https://www.facebook.com/leo19941227)。
請確保你有權限 access 到 superb-website 的 private repo: [superbbenchmark/superb-website](https://github.com/superbbenchmark/superb-website)，所有最新的修正都只有在 private repo，公開的 [public repo](https://github.com/superbbenchmark/website-react) 只是作為其他 SUPERB 系列的 template 使用。

## SUPERB 網站架構

SUPERB 網站由下面幾項主要的 **component** 和他們之間的 **連結** 而成。最重要的是要了解每個 component 主要的功能和他們之間是怎麼連起來的：
- 前端: React(development) + Nginx(Http server)
- 網域名 (superbbenchmark.org): GoDaddy
- Https Certificate (SSL): acme.sh
- 後端: Flask(server) + MySQL(資料庫)
- 使用者登入認證: Google OAuth 2.0

## 前端(Frontend) - React 網頁開發

### 目的

前端負責如何將你的網站「呈現」(present)給使用者，主要負責畫面顯示和與使用者第一線互動。如果一個網站不需要動態更新資料(比方不需要讓使用者A上傳資料，使用者B看到最新的所有資料)，就不需要後端有個資料庫，就代表這個網站只需要「前端」即可。很多單純負責展示個人成果的個人網頁就會是純前端網頁(也只有純前端網頁才能放在 github.io 上)。因為 SUPERB 需要讓使用者上傳 submission，所以需要有後端資料庫，所以前端的責任就是把「後端儲存的資料，順暢且漂亮的展示給使用者看」。

### 內容

這裡的前端是由 React 這個框架寫成。React 定位上只是一個比起直接手刻 html, javascript (js), ccs 更方便的工具。而用 React 這個高階語言寫成的網頁，可以被編譯後產生最低階的 html, js, ccs (稱為靜態檔，static files)。所以作為單純 maintainer 不太需要管 React，除非你想要更動網站顯示的文案。我們會將目前已經寫好的 React 語言編譯成 static files 後，交由 HTTP server 來 serve 這些檔案給來自世界各地的 user。

- [如何安裝需要的套件並編譯出 static files](https://github.com/superbbenchmark/superb-website/tree/master/frontend#instruction-for-setting-up-frontend-server)

## 前端(Frontend) - Nginx HTTP server

### 目的

> 主機必須要有 public IP，假設是 140.112.21.28。

Nginx 負責的是當世界各地的人想透過 browser 連進主機 (by IP 140.112.21.28) 時，每個人當下想看的內容都不一樣，如何最有效率的 serve 我們網站的各個不同網頁和圖片給使用者，是 HTTP server 主要的功用，而 Nginx 是當前特別高效且主流的選項。

### 內容

我們會需要安裝 Nginx，然後把編譯好的 static files 放到 Nginx server 指定的位置。這個位置通常是在`/var/www/html`。詳見：

- [如何安裝 Nginx](https://github.com/superbbenchmark/superb-website?tab=readme-ov-file#initial-step)
- [如何放 static files 並啟動 Nginx server](https://github.com/superbbenchmark/superb-website/tree/master/frontend)

> 到這一步結束，你應該可以透過 browser access `http://140.112.21.28:80`。不過你會發現 leaderboard 還沒有東西，而且你只能用 http 而不能用 https，所以 browser 會跳 warning 說不安全。這是正常的，而我們接下來會解決這些問題。

## 網域名(domain name)

### 目的

網域名(superbbenchmark.org)最重要的目的是要解決人們背不起 IP (140.112.21.28) 的問題。透過在 browser 搜尋欄直接打網域名稱，背後會有個 DNS(domain name system)負責將名稱轉譯成IP，然後就能連到真正連接到該IP的主機。

> - 你也可以直接在搜尋欄打IP，但你就得背IP。
> - IP數字背後代表的是網路線(電纜)，IP號碼一定程度代表了這台主機的地理位置。

### 內容

IP 要花錢買(我們實驗室用的是學校給的)，域名也要花錢買。我們是透過 [GoDaddy](https://www.godaddy.com/en-sg/offers/godaddy?isc=sem3year&countryview=1&currencyType=TWD&cdtl=c_17606417449.g_139428062098.k_aud-651847445488:kwd-88659201.a_684576982462.d_c.ctv_g&bnb=b&gad_source=1&gclid=CjwKCAjw88yxBhBWEiwA7cm6peR4fAcVOReWdw2P6-PpOtyAcGlkjicPzpuTIcqKilz-2Dxuget0UBoC-rYQAvD_BwE) 這個代理網站幫我們買域名(superbbenchmark.org)，買在宏毅老師的帳戶底下。同時，GoDaddy 也會幫我們把 「superbbenchmark.org 要對應到實際實驗室主機的 IP: 140.112.21.28」這件事廣播給全世界的 DNS 機器，這樣全世界的人才都能成功翻譯 superbbenchmark.org 到 140.112.21.28 來 access 我們的主機。

在移動和維護 superb 機器時，需要注意的是如果 superb 機器的實際 IP 哪天不是 140.112.21.28 時，將需要請老師協助，到 GoDaddy 上重新設定 superbbenchmark.org 需要對應到的 IP。設定好後 GoDaddy 會再幫我們廣播給全世界這項更新。

## HTTPS Certification

### 目的

到目前為止，我們的網站已經能讓使用者從搜尋欄打網域名稱連到我們的主機（透過 HTTP）。但這個過程中，所有資訊都是明碼(沒有加密)傳輸。最大的問題是，如果使用者需要打一些個人訊息(比方密碼)，那就有駭客能在訊息(封包)從使用者電腦傳到 superb 主機的路上(經過一堆網路電纜)，截取封包偷取密碼，這樣就是資安問題。因此當前大部分的網頁相關服務(比方想在自己網站上讓使用者利用 Google Auth 來登入)都會要求網站必須支援加密傳輸(Secure Sockets Layer，SSL)，也就是 HTTPS。

> superb 網站就是利用 Google Auth 服務來讓使用者免去註冊的繁瑣程序，直接利用 Google 帳戶就能在 superb 網站上有帳戶，就能直接繳交模型結果。

### 內容

想要啟用 HTTPS，需要向 SSL 認證中心要 certification。基本上就是跟他們說請發放一組 public/private keys（公私鑰）給 superbbenchmark.org 這個網域名。

> 公私鑰的加密原理是，訊息用公鑰加密後，只有私鑰才能解碼。通常我們產生出公私鑰後，會把公鑰散布到全世界，並把私鑰藏起來只有自己知道。這樣全世界的人想跟我們說話時，就能用大家都知道的公鑰加密，放心的在網路上傳輸(所有人都無法解密)，然後傳到我們手上後，只有我們有私鑰能解密。
> 公鑰加密後公鑰無法解碼。

所以任何人連上 superbbenchmark.org 後，就可以用公開的公鑰加密他想傳輸的內容(比方模型結果)，然後傳到我們主機上後，主機有私鑰可以解密。

我們透過 [acme.sh](https://github.com/acmesh-official/acme.sh/blob/master/acme.sh) 這個 script 來自動化「向認證中心要 certification (cert)」這件事。因為 cert 通常有期限，所以期限到了之後，會發現 superb 網站顯示不安全連線。這時就要記得要重新申請 cert。

申請 cert 時，認證中心會需要你證明，你想認證的網域名實際上的確是屬於你的。證明的方式是你要讓它能 access 你的 Nginx server，然後他會自己在 server 裡面加一個檔案，然後它會檢查能不能透過 superbbenchmark.org 這個網域名 access 到他新加的這個檔案。如果可以，就代表你的確是這個網域名的擁有者，然後它就會發更新的 cert 給你。所以注意，執行這個步驟時請確保網路是通的。以下步驟是如何安裝 acme.sh 和如何透過它更新 cert。

- [安裝 acme.sh](https://github.com/acmesh-official/acme.sh?tab=readme-ov-file#2-or-install-from-git)

./acme.sh --install -m [e-mail]

- [更新 cert](https://github.com/superbbenchmark/superb-website/blob/master/resources/re_issue_please_type_commands_manually.sh)：請用 ChatGPT-4 理解每行指令後，一行一行手打。

> 到這一步之後，應該要可以透過 `https://superbbenchmark.org/` access SUPERB 網站了。而 leaderboard 暫時還沒有資料。

## 後端(Backend) - MySQL(資料庫)

### 目的

在上面前端介紹中提到，superb 網站是需要後端的，因為我們要讓使用者能上傳模型結果。而用來儲存模型結果的東西就是資料庫。我們使用很普及的 MySQL。你可以輕易向 ChatGPT-4 問到 MySQL 的任何事情，包括架構和指令。

基本上 MySQL 的架構為：先有 MySQL **server**, 登進 server 後裡面可以有多個 **database**，然後 **database** 中可以有多個 **table** (table 外還有其他類型的物件但這邊用不到)。superb 網站僅使用單一個 database 就叫 `superb`。

我們只要確保 MySQL server 中有這個 database，然後我們有正確的讓後端 server 知道 MySQL server 的位置 (IP & Port) 和他需要的 database 名稱 (superb)。後端 server 就能順利的到資料庫中撈資料，然後傳給前端，由前端把資料漂亮的呈現給使用者。這個過程中：

- 前端的程式碼是跑在使用者的電腦上，specifically 他的 browser。
- 後端 sever 是跑在 superb 主機的 [140.112.21.28:5000](https://github.com/superbbenchmark/superb-website/blob/1eb9aa16f27ddf87fb2668540128a59780cfcfec/backend/app.ini#L4)。前端需要資料的時候，會透過 HTTP API 向 140.112.21.28:5000 要資料。
- 資料庫是開在 superb 主機的 [localhost:3306](https://github.com/superbbenchmark/superb-website/blob/1eb9aa16f27ddf87fb2668540128a59780cfcfec/backend/.env#L1) (也就是 localhost:3306) 後端 server 只是當作和前端溝通的代理人，本身沒有資料，資料是存在資料庫裡。所以後端 server 接到來自前端的 request 時，會再根據 request 內容向 localhost:3306 要相關的原始資料，然後把原始資料 parse 成前端想要的格式，再回傳給前端。

### 內容

- [安裝 MySQL](https://github.com/superbbenchmark/superb-website/tree/master?tab=readme-ov-file#set-up-database)
- 設定資料庫之帳號密碼時，請使用：
- 帳號：superb
- 密碼：superbbenchmark
- [確保後端 server 有連上 MySQL 中的 superb database](https://github.com/superbbenchmark/superb-website/blob/1eb9aa16f27ddf87fb2668540128a59780cfcfec/backend/.env#L1): 這邊照理說都不需要更動就能 work，只要前面的步驟沒有更動帳號密碼、database 名稱的話。但以防東西東西不 work 了，還是了解一下原理才能 debug。
- **`mysql+pymysql://superb:superbbenchmark@127.0.0.1:3306/superb`**
- **`superb`**: This is the username used to authenticate with the MySQL database.
- **`superbbenchmark`**: This is the password for the superb user.
- **`127.0.0.1`**: This is the host address where the MySQL server is running. 127.0.0.1 is the localhost address, meaning the server is running on the same machine as the client (or it's being accessed through some local port forwarding setup).
- **`3306`**: This is the port number on which the MySQL server is listening. 3306 is the default MySQL port.
- **`superb`**: This is the name of the database to which SQLAlchemy will connect.

## 後端(Backend) - Server

### 目的

後端 server 於整個 website 中的定位在上一個 section 中描述了。這邊只講要如何架起來。

### 內容

- [進到 backend 資料夾執行以下指令](https://github.com/superbbenchmark/superb-website/tree/master/backend#instruction-for-setting-up-backend-server): 請照著`For production (w/ independent environment)`。
- 只是要把 server launch 起來的話，可以直接跑 `./backend/run.sh`。

## Google OAuth 2.0

### 目的

我們允許 superb 參加者上傳他們自己的模型結果。這個步驟需要讓參加者在 superb 網站上有自己的帳戶。但由我們自己來 maintain 帳戶註冊和密碼維護太麻煩也不安全，所以我們採用更安全又更方便的方法：利用 Google Auth。也就是很多網站會讓你可以一鍵用 Google 帳號直接登入的功能。

### 內容

這個登入流程在 superb 網站上 involve 下面幾點：
- 作為 website owner，向 Google 申請一個 Client
- Google 帳密：`[e-mail]` / `Speechlab531`
- [(已)申請位置](https://console.cloud.google.com/apis/credentials?authuser=2&pli=1&project=superb-website-318006)
- Client ID: `796679159105-6335p2q2ub5pr15lnf3g2cqkhnucmvkl.apps.googleusercontent.com`
- 前端網頁讓使用者透過 Google 登入按鈕登入時，結合這個 Client ID，Google 會發放一個 JSON Web Token (JWT)，此 JWT 就代表了該使用者的一切個人資訊，透過 Client ID 由 Google 方加密，所以可以安全的在網路上傳輸。
- 此 JWT 傳到後端後，後端因為也有 Client ID，所以可以向 Google 方要求解密此 token 得到使用者的訊息，包括 email 和姓名。
- 我們以 **email 作為主要代表使用者的帳戶 ID**，將使用者多次上傳的結果都透過 email 整合在同一個帳戶下。

作為網站維護者，理論上在移植和維護時應該是不需要動到這塊。但還是有基本的理解會比較好。***最需要注意的是，Google Auth要求網站一定要是 HTTPS 連線，所以必須要先把前面 section 中 HTTPS certification 的地方確定弄好了這邊才不會出事。***

## Backup

- 大部分的內容都儲存在 superb 網站的 [private repo](https://github.com/superbbenchmark/superb-website) 中。
- 特別需要定期 backup 的是資料庫，可以透過以下 [script](https://github.com/superbbenchmark/superb-website/blob/master/resources/sql_backup.sh) 進行備份。並請將備份的 **.sql** 檔案上傳到此 [Gdrive 資料夾](https://drive.google.com/drive/folders/1NwjdX-t5sqfkpmU_TvSL-OfGQsMDZqim?usp=sharing)。
- superb 網站支援使用者下載他之前上傳過的 submission。而這些 submission 是存放在 `backend/upload` 中。請定期同步備份(rsync) `backend/upload/` 中的 submission folders 和外接硬碟的 `upload_backup/`:

    rsync -avP backend/upload/* ext_disk/upload_backup/

> 外接硬碟長相如下：

<img src="https://imgur.com/WyUYQbQ.png)" alt="外接硬碟" width="200"/>

## Re-launch SUPERB website

以下為重新移動並重新啟動網站要注意關於 **data 移植** 的事項。

### 資料庫

在任意電腦上的任意 MySQL server 中，新建一個空的 database(命名為 superb) 然後把當初備份好的 [SUPERB database](https://drive.google.com/drive/folders/1NwjdX-t5sqfkpmU_TvSL-OfGQsMDZqim?usp=sharing) 整份 dump 進去 by 以下指令：

# mysql -u [sql_user_name] -p [database_name] < [backup_file]

# -p means prompt for password, and the password is: superbbenchmark

# [database_name] is the positional argument, and is
# not the argument for -p

mysql -u superb -p superb < backup_20240427.sql

### 上傳紀錄

將外接硬碟中的上傳紀錄 sync 回新的主機中：

mkdir backend/upload/
rsync -avP ext_disk/upload_backup/* backend/upload/

## Final Check

Please download the sample [predict.zip](https://superbbenchmark.org/api/download/example) and follow the [documented submission pipeline](https://github.com/s3prl/s3prl/blob/main/s3prl/downstream/docs/superb.md#leaderboard-submission) to re-submit the sample results. The scores of each task should be exactly the same as the **`admin_baseline`** row in the current SUPERB leaderboard (I submitted that row with this exact `predict.zip` file.)