Backstage Quick Start

Run Local

先決條件

• Ubuntu 24.04.2 LTS
• Node Version 20 (It is recommended to use volta or nvm to manage node versions)

  # Install nvm (Node Version Manager)
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
  
  # Load nvm in your current shell (also opens new shells with nvm)
  export NVM_DIR="$HOME/.nvm"
  [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
  
  # Install and use Node 20 (latest 20.x)
  nvm install 20
  nvm use 20
  nvm alias default 20
  
  # Verify
  node -v
  npm -v
• Yarn to manage dependencies

  # Install Corepack, an intermediary tool that will let you configure your package manager version on a per-project basis
  npm install -g corepack
  
  # update Yarn to the 4.4.1 version
  yarn set version 4.4.1
• Git for source control (OS 預設就有裝了)
• docker

  # Add Docker's official GPG key:
  sudo apt-get update
  sudo apt-get install ca-certificates curl
  sudo install -m 0755 -d /etc/apt/keyrings
  sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
  sudo chmod a+r /etc/apt/keyrings/docker.asc
  
  # Add the repository to Apt sources:
  echo \
    "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
    $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
    sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  sudo apt-get update
  
  # Install the Docker packages
  sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Creating an Instance

首先透過 npx 執行 Backstage 的 create-app 腳本：

npx @backstage/create-app

系統將提示輸入 Backstage 實例的名稱；該名稱將用於命名儲存它的目錄。在本例中，我們選擇了 terroir-portal 這個名稱。

Need to install the following packages:
@backstage/create-app@0.7.3
Ok to proceed? (y) y

? Enter a name for the app [required] terroir-portal

腳本將複製 Backstage 的範本及其目錄和檔案並安裝其所有相依性。

現在會看到以下目錄結構：

─ packages
    ├─ app
            └─ package.json
    └─ backend
            └─ package.json
─ app-config.yaml
─ catalog-info.yaml
─ package.json

• 請注意，這裡有多個 package.json 文件 ，這是因為你的 Backstage 實例是以 monorepo 的方式實現的。因此，前端 ( app ) 和後端 ( backend ) 都有各自的依賴項，可以獨立部署。
• 也要注意 catalog-info.yaml 檔案。 Backstage 使用這個元資料檔案將自身加入軟體目錄。沒錯，Backstage 想要追蹤組織中的所有軟體資產，包括它自己！
• 最後，請查看 app-config.yaml 。這是主配置文件，您可以在其中定義實例的名稱並設定後端、身份驗證和其他整合的選項。

現在，讓我們看看 Backstage 是什麼樣子的。在終端機中導航到實例的目錄並執行：

cd terroir-portal; yarn start

現在，讓我們開始透過更改 Backstage 實例的名稱來讓它更具您的特色。轉到您的 app-config.yaml 文件並將應用程式的標題變更為您自己的標題。在我們的例子中，它看起來像這樣：

nano app-config.yaml

修改內容如下：

• 把預設 localhost 改成本機網卡的 ip

app:
  title: Terroir Portal
  baseUrl: http://192.168.11.133:3000

organization: 
  name: Terroir Technologies

backend:
  baseUrl: http://192.168.11.133:7007

  cors:
    origin: http://192.168.11.133:3000

開發後台伺服器將會取得更改，您將在瀏覽器中看到名稱！

Installing PostgreSQL

get PostgreSQL through apt-get:

sudo apt-get install -y postgresql

在本課程中，您將使用預設的 postgres 使用者。因此，讓我們為該用戶設定一個密碼。透過以下方式看到相同的提示符號：

sudo -u postgres psql

使用此命令將使用者 postgres 密碼設定為您想要的任何密碼（ secret 是密碼範例）：

ALTER USER postgres PASSWORD 'secret'

Setting up Postgres in Backstage

Backstage 可讓您針對不同的環境使用不同的配置，這非常方便。您已經處理了主設定檔 app-config.yaml 來設定您的組織名稱。此外，您還會發現 app-config.local.yaml 和 app-config.production.yaml ，它們分別用於本機環境和生產環境。

目前，您將使用 app-config.local.yaml 檔案 。 Backstage 預設將此檔案包含在 .gitignore 檔案中，這表示您在此處寫入的任何內容都不會被提交或推送到上游。這可以讓您更安心地將本地開發的機密文件存放在此。

若要在您的機器上使用 Postgres 設定 Backstage，請將以下內容新增至您的 app-config.local.yaml ：

nano app-config.local.yaml

檔案內容如下：

backend:
  database:
    connection:
      host: 192.168.11.133
      # Default postgresql port, change accordingly to your case
      port: 5432
      user: postgres
      # The password you set earlier
      password: secret

停止實例，然後使用 yarn start 再次運行。瀏覽器應該會再次開啟 http://192.168.11.133:3000/ 並顯示相同的 Catalog 畫面。

Setting up Authentication

您很可能需要對開發者入口網站進行身份驗證。 Backstage 支援 11 個開箱即用的身份驗證提供程序，包括 Okta、Google 和自訂 OAuth 2 代理程式 。在本課程中，您將開始使用 GitHub 進行身份驗證，因為在接下來的章節中您將繼續使用 GitHub。

若要啟用 GitHub 身份驗證，您必須：

1. 設定 GitHub OAuth 應用
2. 新增 GitHub 身份驗證配置
3. 在前端啟用 GitHub 作為身份驗證方法
4. 新增 GitHub 後端提供者
5. 將您的 GitHub 使用者名稱新增至使用者實體

nano app-config.local.yaml

新增內容如下

auth:
  environment: development
  providers:
    github:
      development:
        clientId: Ov23liI1teDPwZFZR7Mi
        clientSecret: 64e2b72bf62215b6e841ac78d061c52e7fe5d95c
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName

nano packages/app/src/App.tsx

檔案內容：

// auth
backend.add(import('@backstage/plugin-auth-backend-module-github-provider'));