Lighthouse CI 서버 구축하기

Publish date: Mar 31, 2023
Last updated: Apr 2, 2023

Tags:

버스하냥 프로젝트에 Lighthouse CI를 도입하면서, Lighthouse CI 서버를 구축해보았습니다.

도입배경

버스하냥 서비스 개발을 할 때, 저희 팀은 항상 더 빠르고 사용자 친화적으로 만들기 위해 여러 가지 시도와 노력을 합니다. 그중에서 신경을 쓰는 지표 중 하나가 바로 Google에서 제공하는 Lighthouse입니다. 하지만 이 지표는 디바이스마다 특히 성능 부분에서 점수가 다르게 나올 수 있으며, 개발자가 매번 수정하고 직접 테스트를 돌려야 하는 불편함이 있습니다. 그래서 이번에 PR이 생겼을 때 자동으로 Lighthouse 결과를 생성해 주는 Lighthouse CI를 도입하게 되었습니다.

Lighthouse란?

Lighthouse는 웹 페이지의 품질을 측정하고 개선하기 위한 오픈 소스 도구입니다. 웹 사이트의 성능, 접근성, 검색 엔진 최적화 (SEO), 모범 사례 및 프로그레시브 웹 앱 (PWA) 기준을 감사합니다. Lighthouse는 웹 페이지의 성능과 품질을 개선하기 위해 수행할 수 있는 작업에 대한 통찰력을 제공하는 보고서를 생성합니다. 기본적으로 Lighthouse는 Chrome DevTools 패널에서 사용할 수 있습니다.

Google Lighthouse is a open-source tool developed by Google that audits web pages to measure their performance, accessibility, best practices, SEO and PWA. It generates a report that provides insights into how well the web page performs and what can be done to improve its quality.

Lighthouse CI

Lighthouse CI는 Lighthouse 결과를 CLI로 실행하고, 그 결과를 파이프라인에 연결하여 저장하고, 저장된 결과를 비교할 수 있게끔 만들어주는 서비스입니다. 저희는 이 서비스를 메인 레포에 연결하여 PR이 생성될 때마다 Lighthouse 결과를 생성하고, 저장하고, 비교하여 결과를 보여주는 서비스를 구축하려고 합니다.

Lighthouse CI 설정하기

Lighthouse CI는 GitHub Actions로 구축할 예정입니다. 별다른 환경 구축 필요 없이 CLI로 실행이 가능하기 때문에 간단하게 구축이 가능합니다.

우선 Lighthouse 설정 파일을 생성합니다. 프로젝트 루트 폴더에 lighthouserc.js 파일을 생성하고 아래와 같이 설정합니다.

module.exports = {
  ci: {
    collect: {
      staticDistDir: './dist',
      url: 'http://localhost/index.html',
      numberOfRuns: 5,
    },
    upload: {
      target: 'temporary-public-storage',
      githubAppToken: process.env.LHCI_GITHUB_APP_TOKEN,
    },
  },
}

staticDistDir은 빌드 된 파일이 저장된 폴더를 지정합니다. 저희 프로젝트는 빌드 시 dist폴더에 저장되어 다음과 같이 설정하였습니다. upload는 Lighthouse 결과를 어디에 저장할지 지정합니다. temporary-public-storage는 Google에서 제공하는 임시 저장소를 사용하겠다는 옵션입니다.

GitHub App Token은 GitHub에서 Status Check를 표시하기 위해 필요한 GitHub App의 토큰입니다. 여기를 참고하여 앱을 설치 후, 앱 설치 완료 페이지에서 나오는 토큰을 사용하면 됩니다.

더 상세한 설정 방법은 여기서 확인할 수 있습니다.

다음으로는 GitHub Actions에서 workflow를 설정합니다. .github/workflows/lighthouse.yml 파일을 생성하고 아래와 같이 설정합니다.

name: Lighthouse CI
on: [pull_request]
jobs:
  lhci:
    name: Generate Lighthouse Report
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v3
      - name: NodeJS Setup
        uses: actions/setup-node@v3
        with:
            node-version: 16
      - name: Check dependencies & build
        run: |
          yarn install
          yarn build          
      - name: Run Lighthouse CI
        id: step_lhci
        run: yarn dlx @lhci/cli autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

저희 서비스는 yarn 패키지 매니저를 사용하고 있기 때문에 yarn을 사용했습니다. 만약 npm을 사용하신다면 npm으로 변경하면 됩니다. 또한 yarn v1.x을 사용하신다면 yarn global add @lhci/cli를 사용하면 됩니다.

이제 기본적인 CI 구축은 끝났습니다. PR을 생성할 때마다 Google에서 제공하는 임시 저장소에 결과가 저장되고, 일정 기간 동안 그 결과를 확인할 수 있습니다.

Lighthouse 서버 구축하기

위에서 언급했듯이 이대로 구축을 완료하게 되면 Google에서 제공하는 임시 저장소에 결과가 저장되고, 일정 기간 동안 그 결과를 확인할 수 있습니다. 하지만 저희는 이 결과 데이터를 저희가 가지고 있기를 원하였고, 과거의 기록들도 유효기간 없이 보유하고 싶었습니다. 따라서 저희 소유의 LightHouse CI 서버를 구축하였습니다. 가이드는 여기를 참고하였습니다.

먼저, Lighthouse CI 서버를 구축하기 위해서는 인터넷이 연결되어 있고 Node v16 이상이 설치되어 있어야 합니다. 또한, SQLite, MySQL, PostgreSQL 중 하나의 데이터베이스 저장소가 필요합니다.

버스하냥은 무보수 비영리 단체이기 때문에 운영 비용 절감을 위해 유료 서버를 구축하는 것은 최대한 자제하여야 합니다. 따라서 저희는 무료로 데이터베이스 서버를 만들 수 있는 Cloudtype을 사용하였습니다.

서버는 node가 돌아가가고 인터넷만 연결되어 있으면 어떤 서비스이든 상관없습니다. DB 서버를 따로 분리하였기 때문에 Static page 제공 서비스로도 충분히 구축이 가능합니다. 저희는 플랫폼을 통일하고자 마찬가지로 Cloudtype을 사용하였습니다.

const {createServer} = require('@lhci/server');

console.log('Starting server...');
createServer({
  port: 3000,
  storage: {
    storageMethod: 'sql',
    sqlDialect: 'postgres',
    sqlConnectionUrl: process.env.DATABASE_URL
  },
  basicAuth: {
    username: process.env.AUTH_USERNAME,
    password: process.env.AUTH_PASSWORD
  }
}).then(({port}) => console.log('LHCI listening on port', port));

위와 같이 server.js 파일을 생성하여 배포합니다. 여기서 sqlConnectionUrl에는 데이터베이스의 주소가 들어가야 합니다. 저희는 클라우드 서비스를 사용하였기 때문에 DATABASE_URL이라는 환경 변수를 따로 설정해 두었습니다.. 만약 다른 서비스를 사용하신다면 해당 서비스의 환경 변수를 참고하면 됩니다.

basicAuth에는 사용자 인증을 위한 정보가 들어가게 됩니다. 저희는 이 서비스를 관계자만 열람할 수 있게 하기 위해 사용자 인증을 추가하였습니다. 만약 외부에도 CI 서버를 공개하고자 한다면 해당 옵션을 제거하면 됩니다. 마찬가지로 아이디와 비번은 환경 변수로 설정해 두었습니다.

도메인 연결 후 서비스에 접속을 하면 아래와 같이 사용자 인증을 요구합니다.

로그인을 하면 다음과 같은 화면이 나타나게 됩니다. 이로써 Lighthouse CI 서버 구축이 완료되었습니다.

GitHub Actions와 Lighthouse CI 서버 연결하기

아까 위에서 GitHub Actions를 통해서 구축한 Lighthouse CI는, PR 생성 후 자동으로 Lighthouse 검사를 한 후, Google의 임시 저장소에 결과가 저장되는 방식으로 설정되었습니다. 이번에는 검사 결과를 방금 위에서 구축한 저희의 Lighthouse CI 서버에 저장하도록 설정해 보겠습니다.

아까 생성한 lighthouserc.js 파일을 다음과 같이 수정합니다.

module.exports = {
  ci: {
    collect: {
      staticDistDir: './dist',
      url: 'http://localhost/index.html',
      numberOfRuns: 5,
    },
    upload: {
      target: 'lhci',
      serverBaseUrl: 'https://lighthouse.hybus.app',
      token: process.env.LHCI_TOKEN,
      githubAppToken: process.env.LHCI_GITHUB_APP_TOKEN,
      basicAuth: {
        username: process.env.LHCI_USERNAME,
        password: process.env.LHCI_PASSWORD,
      },
    },
  },
}

target을 변경함으로써, 저희가 구축한 Lighthouse CI 서버에 저장하도록 설정하였습니다. serverBaseUrl에는 저희가 구축한 Lighthouse CI 서버의 주소가 들어가게 됩니다.

token은 Lighthouse CI 서버에 접근하기 위한 토큰입니다. 이 토큰은 로컬에서 lhci wizard를 통해 프로젝트를 추가하면서 생성할 수 있습니다. 아래와 같이 lhci wizard를 실행합니다.

lhci wizard를 실행하면 위와 같은 화면이 나타납니다. 위 토큰 란에는 build token을 입력하면 됩니다.

위에서 추가한 환경 변수들을 GitHub Actions에서 사용할 수 있도록 실행 환경에 환경 변수를 추가해 줍니다. 아래와 같이 env에 환경 변수를 추가하면 됩니다.

name: Lighthouse CI
on: [pull_request]
jobs:
  lhci:
    name: Generate Lighthouse Report
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v3
      - name: NodeJS Setup
        uses: actions/setup-node@v3
        with:
            node-version: 16
      - name: Check dependencies & build
        run: |
          yarn install
          yarn build          
      - name: Run Lighthouse CI
        id: step_lhci
        run: yarn dlx @lhci/cli autorun
        env:
          LHCI_TOKEN: ${{ secrets.LHCI_TOKEN }}
          LHCI_USERNAME: ${{ secrets.LHCI_USERNAME }}
          LHCI_PASSWORD: ${{ secrets.LHCI_PASSWORD }}
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
      - name: Post Link to Lighthouse Report
        uses: thollander/actions-comment-pull-request@v2
        with:
          comment_tag: lighthouse
          message: |
            Check out your Lighthouse Report: https://lighthouse.hybus.app/app/projects/hybus-genesis-production            
          mode: recreate

추가적으로 Lighthouse 결과가 생성되었으면, 생성된 결과를 확인할 수 있도록 Lighthouse 링크를 PR에 댓글로 남겨 주는 기능을 추가하였습니다.

결과

세팅을 끝낸 후, PR을 열면 다음과 같이 Lighthouse CI가 자동으로 실행되는 것을 확인할 수 있습니다.

또한, Lighthouse CI 서버에 접속하여 결과를 확인할 수 있습니다.

기존에 Chrome DevTools에서 사용하던 UI로 확인하고 싶으면 jump straight to the Lighthouse report를 클릭하면 됩니다. 해당 버튼을 클릭하게 되면 Google에서 제공하는 Lighthouse 결과 뷰어로 결과를 확인할 수 있습니다.

cf) 현재 Lighthouse CI 서버에서 root url에서부터 접근하지 않았을 시 웹 UI가 고장 나는 문제가 있습니다. 해당 오류에 대해 GitHub에 Issue를 남겨놓은 상태입니다.