在 AWS EC2 上建置 Verdaccio 排雷記

Posted on Edited on In Views: Disqus:

環境以及使用版本

  • AWS EC2, Kubernetes Version: 1.21
  • Verdaccio, Version: v5.8.0

為什麼選擇 Verdaccio

Verdaccio 是義大利文的棕綠、橄欖綠的意思，唸法: ver搭起偶，念起來潮度百分百，而且同事聽不懂你在說什麼。

這個工具是一套開源的 NPM 的套件包管理工具 (Registry)，假設企業內部有些自有的 JavaScript 套件只能放在內部做管理，就可以自建這個 NPM Registry。假設企業內部有用 GitHub 或 GitHub Enterprise，也可以使用 GitHub NPM Registry，比較詳細的介紹以及使用方式可以參考這篇 - GitHub - Working with the NPM Registry，要注意的是如果你的專案設定是 private 就無法使用這個功能。本次安裝 Verdaccio 純粹是因為帳號可以獨立出來，不需要跟 GitHub 綁定。

關於 Verdaccio 的介紹，網路上有非常多的文章，本機安裝和基本的操作可以看一下這一篇 - 神Q超人 - 用 Verdaccio 快速建立專屬的 private npm proxy 並部署到 Heroku 上！ 本篇是紀錄安裝在企業內部環境時可能會踩到的雷，還有一些建置時會需要考量的點。

如果是用 EC2 安裝的話，架構大概會長這樣：
upload successful

  • ALB 可以自行替換成 Nginx 等他牌 Load Balancer
  • EFS 可以替換成 EBS 或其他 NAS 服務 (需要注意的是，EBS 一次只能給一台 EC2 掛載，若要建構多個 EC2 instances 做負載均衡的話，請使用 EFS)

建置過程

除去建置 Nginx 以及添加域名等工作，純安裝大概可以分為四個步驟：

  1. 建置 ec2
  2. 安裝 NodeJS
  3. 安裝 Verdaccio, pm2(Optional)
  4. 修改設定檔，以 daemon 的形式運行 Verdaccio

首先我是參考 Medium - Free Private NPM with Verdaccio and AWS 這篇文章作為安裝的步驟依據，中間根據自己環境加以修改：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
# 安裝 NodeJS, Verdaccio 以及 pm2
curl --silent --location https://rpm.nodesource.com/setup_14.x | bash -

yum install -y nodejs

# 確認一下 Node 版本號碼
node -v

npm install verdaccio -g

# 先試著跑起來看看有沒有安裝成功
verdaccio

# 要維持 Verdaccio 不死可以選 pm2 / forever 或 Linux 自帶的 Systemd 跑起來
npm i pm2 -g

# 前面沒有擋 Load Balancer 或純粹自己玩可以填 localhost，或是填域名，但這邊我有用 Nginx，此步驟就可以略過
npm set registry http://localhost:4873
# 不設置憑證
npm set ca null

# 預設跑起來會吃這個設定檔，要自行創建
vim .config/verdaccio/config.yaml

# 可以用 verdaccio 命令跑起來看看設定檔寫的對不對
verdaccio --config .config/verdaccio/config.yaml

# 因為後來決定用 Systemd 來跑，所以要複製一下設定檔
cp .config/verdaccio/config.yaml /etc/verdaccio/config.yaml

# 複製 Verdaccio 的服務單位設定檔到系統的 Systemd 服務單位目錄
sudo cp /usr/lib/node_modules/verdaccio/systemd/verdaccio.service /lib/systemd/system/

# 確認一下設定檔真的有複製到
vim /lib/systemd/system/verdaccio.service

# 重新載入 Systemd 設定檔
systemctl daemon-reload

# 啟動 Verdaccio
systemctl start verdaccio

# 確認 Verdaccio 狀態
systemctl status verdaccio

# 假設你是用自己的域名，要寫入這個環境變數，使用者載入靜態資源 URL 才會指到你的域名，否則會顯示 404 找不到靜態資源
export VERDACCIO_PUBLIC_URL="https://${your npm registry domain name}/"

# 因為我是用 Systemd 跑起來的，所以要把上面的環境變數寫進採用優先權值較高的設定檔中，如果跑這個命令，Systemd 會幫你建立相關的目錄，並且新增 override.conf 這個檔案
systemctl edit verdaccio

# 之後有需要的話也可以直接編輯 override.conf 這個設定檔
vim /etc/systemd/system/verdaccio.service.d/override.conf

# 記得每次編輯完設定檔都要重新載入 Systemd 服務並重跑
systemctl daemon-reload && systemctl restart verdaccio

安裝完畢，照著說明加入使用者就可以開始上傳 NPM 套件了，非常方便喔！

upload successful

需要注意的一些設定

雖然安裝看起來很簡單，但實際上還是花了我不少時間，主要是在排除靜態資源顯示不出來的問題…，結果發現是域名要寫在環境變數裡，只能說文件要好好看ＸＤ

這是 Verdaccio 的服務單位 (Service Unit) 設定檔，假設 Daemon 跑不起來時，可以試著依照錯誤調整 Restart 的參數看看，也可以調整設定檔位置：

1
2
3
4
5
6
7
8
9
10
11
[Unit]
Description=Verdaccio lightweight npm proxy registry

[Service]
Type=simple
Restart=on-failure
User=verdaccio
ExecStart=/usr/bin/verdaccio --config /etc/verdaccio/config.yaml

[Install]
WantedBy=multi-user.target

這個是環境變數的設定檔：

1
2
[Service]
Environment="VERDACCIO_PUBLIC_URL=https://${your npm registry domain name}/"

記得要在設定檔中開放所有連線，把 localhost 改成 0.0.0.0：

1
2
3
4
5
6
7
listen:
# - localhost:4873            # default value
# - http://localhost:4873     # same thing
 - 0.0.0.0:4873              # listen on all addresses (INADDR_ANY)
# - https://example.org:4873  # if you want to use https
# - [::1]:4873                # ipv6
# - unix:/tmp/verdaccio.sock    # unix socket

如果有覆寫路徑的需求的話，可以在設定檔裡的 url_prefix 加入覆寫的路徑 (subpath) ：

1
2
# if you use nginx with custom path, use this to override links
# url_prefix: https://${your npm registry domain name}/

歡迎一起加入 Verdaccio 的翻譯行列

我覺得 Verdaccio 蠻好用的，在 GitHub 上面星星數有一萬三千多顆，如果能夠貢獻到的話，老年也可以跟孫子女們話當年（?）。如果想要對開源專案有所貢獻 (contribution) 的話，翻譯文件或是使用者介面算是最平易近人的貢獻方式了，而且這個專案使用的翻譯協作工具也提供蠻好的使用者體驗，所以如果有人想一起加入翻譯這個專案的話，歡迎加入翻譯行列喔！

Reference

🍀 神Q超人 - 用 Verdaccio 快速建立專屬的 private npm proxy 並部署到 Heroku 上！
🍀 StackOverFlow - How to yum install NodeJS on Amazon Linux
🍀 GitHub - Working with the NPM Registry
🍀 Medium - Free Private NPM with Verdaccio and AWS
🍀 Verdaccio 官方文件 - Overriding the Public URL
🍀 Verdaccio 翻譯專案
🍀 [Tsung’s Blog - Linux systemd 寫 可自動啟動的 Daemon Service](https://blog.longwin.com.tw/2018/02Linux systemd 寫 可自動啟動的 Daemon Service/linux-systemd-auto-start-daemon-service-2018/)
🍀 How to resolve start limit hit
🍀 使用verdaccio 搭建 私有npm库，使用nginx 代理https域名遇到的一些问题总结
🍀 環境變數使用方式大全
🍀 Verdaccio 官方文件 - Reverse Proxy
🍀 How to set environment variable in systemd service