How to use docker launch JupyterHub on GCP and login with OAuth?

由於公司有相關的需求，就埋頭來研究一下 JupyterHub 的安裝與建置，網路上雖然有很多相關的參考文章了依然的撞了很多牆，除了紀錄有點舊以外，官網的相關說明其實有些地方我也看得一頭霧水，所以來紀錄一下，最後也把相關設定包入 docker 以利後需使用，有任何錯誤歡迎指正。

本文學習重點

1.利用 docker 快速建立多人使用的 JupyterHub

2.使用 OAuth驗證 使用公司 gmail 作為登入帳號

備註：
本教學使用的環境預設使用者已熟知於 如何於GCP環境架設VM，並對 Docker 有基礎的了解(使用自己的環境也不會有問題，都已 docker 化，可依需求調整 dockerfile)。

1.安裝 Docker

若有安裝過了請跳過此步驟。

• docker : 前往 docker 官網 選擇自己合適的作業系統 (連結為 ubuntu 的範例)，跟著步驟安裝即可。
• docker-compose : 前往 官網 依照相對應 OS 安裝即可。

2.Clone repository

基本上都已經包好了，clone 下來就能使用

 git clone https://github.com/ChiLunHuang/jupyterhub.git

3. .env 設定

cd 進入資料夾操作，複製 .env 檔並依照需求填入相關參數

  cp env.example .env

• SHARE_FOLDER 為所有使用者在 container 的 code ，方便未來移植、複製環境
• port 預設為 8000 可依需求更改 (gcp 環境新開 port 請更改防火牆設定)

4.OAuth Authenticator 設定

這個部分就稍微複雜麻煩點了，由於 GCP 服務更新變動的相當平凡，網路教學可能隨時會過時導致資訊很不完整，請特別注意。

GCP 啟用 oauth 服務請見以下教學：

1.在 GCP 左方導覽列中尋找 API和服務

2.第一次使用要 先進入 OAuth 同意畫面 填入相關資料，還蠻容易理解的我就不多做說明。

當中有個 已授權網域 請填寫公司的網域名稱，ex:google.com，否則下一步會出錯

2.接下來進入憑證的步驟，主要是要取得 certificate 用戶端 ID(client_id) 與 用戶端密碼(client_secret)

• 點擊導覽列的憑證 > 點擊建立憑證按鈕 > OAuth 用戶端ID

  

• 填寫相關資料 (參考下圖)

  • 網路應用程式
  • 名稱
  • 已授權的 JavaScript 來源 (請將範例中的網域位置換成自己相對應的網域且必須跟上一步驟的已授權網域相同，否則會跟我有一樣的錯誤訊息)

  若上一步驟 已授權網域 填寫的是 lab.tw，這步驟可能就會如下圖一樣(hostname.domain)

  

  相關資訊也可參考：config 與 certificate 設定參考

5.jupyterhub_config.py 設定

• 複製設定檔

  cp config_folder/example.jupyterhub_config.py config_folder/jupyterhub_config.py

• 若有使用 docker-compose down 再重新啟動後使用者資料都會重置， config_folder 資料夾內的資料也是方便未來移植、複製使用者資料

• 設定上一步驟得到的憑證以及填入自己的 domain 、 host，需要設定的有 oauth_callback_url、client_id、client_secret、hosted_domain、login_service

  • oauth_callback_url：填入剛剛申請憑證的那個 callback url
  • client_id、client_secret:填入剛剛申請憑證的兩組號碼
  • hosted_domain：允許進入網頁的domain，例如公司的 xxx.com，可設定多組使用逗號分隔 [‘hosted_domain 1’,’hosted_domain 2’]
  • login_service：登入時的顯示資訊，自由更改

  from oauthenticator.google import LocalGoogleOAuthenticator
  c.JupyterHub.authenticator_class = LocalGoogleOAuthenticator
  # use Google OAuthenticator for local users
  c.JupyterHub.authenticator_class = 'oauthenticator.LocalGoogleOAuthenticator'
  # Need to create certificate in gcp interface and get client_id, client_secret
  c.GoogleOAuthenticator.oauth_callback_url = 'http://your_domain_url:8000/hub/oauth_callback'
  c.GoogleOAuthenticator.client_id = 'your_client_id'
  c.GoogleOAuthenticator.client_secret = 'your_client_secret'
  c.GoogleOAuthenticator.hosted_domain = ['host_name']
  c.GoogleOAuthenticator.login_service = 'Login with email'

  • 補充： 使用 Email 新增使用者可能會遇到下方訊息，解決方式參考

    Please enter a username matching the regular expression configured via the NAME_REGEX

    要加入 c.Authenticator.add_user_cmd = [‘adduser’, ‘-q’, ‘–gecos’, ‘“”‘, ‘–disabled-password’, ‘–force-badname’]

  • 其他 config 設定例如白名單、黑名單(whitelist & blacklist)基本上官網就很清楚了，就不贅述。如果沒有特別需求，直接使用 repo 裡的設定更改即可。

6.啟動 Build image and start containers

  docker-compose up -d

• Build images：第一次啟動/或改動 dockerfile

  docker-compose up --build -d

• 手動重啟

  docker-compose restart

7.暫停 Stops containers

  docker-compose down

8.JupyterHub URL

依需求更換 port，並確認是否可以連線

  http://<IP-Adress>:8000

9.使用 OAuth 驗證帳號設定

在 admin 頁面新增即可

  http://<yourdomain.tw>:8000/hub/admin

10.非使用 OAuth 驗證帳號設定(新增/刪除/修改)

提供不使用 google gmail 作為帳號的方式：

1.更新

  sudo docker exec -it jupyterhub passwd <user>

2.新增

  sudo docker exec -it jupyterhub useradd --create-home <user>
  sudo docker exec -it jupyterhub passwd <user>

若有新增使用者必須在 admin 頁面也新增一樣名稱的使用者，否則 Jupyter 不會認得

  http://<IP-Adress>:8000/hub/admin

3.刪除

未確定該使用者的資料都不需要時請勿加上 -r

  sudo docker exec -it jupyterhub userdel <user>

參考資料與說明

• Config 設定上可以參考下方兩篇文章:

https://github.com/jupyterhub/oauthenticator
https://cadlab.mde.tw/post/jupyterhub-oauth2-deng-ru-she-ding.html

• 這個 docker-compose.yml 直接使用官網上的 image，若有其他版本需求再自行更改 Dockerfile

• 以上為簡略的說明，若有疑問請在留言區發問，若是文章有幫助到你也請在 github.com 按個星星讓我知道，謝謝。