[Electron 데스크톱 앱 개발] #10: Electron 자동 업데이트 기능 구현하기

 

이번에는 지금까지 만든 Huni Roulette에 자동 업데이트 기능을 적용해 보겠습니다.

이전에 배포했던 Huni Roulette를 직접 다시 설치하지 않아도,

새로운 버전이 출시되면 앱에서 자동으로 업데이트할 수 있도록 구현해 보겠습니다.

 

현재 프로젝트는 Electron Forge와 Squirrel.Windows를 사용하고 있습니다. 기존 프로젝트 설정을 유지하면서 GitHub Release를 통해 업데이트 파일을 제공하고, 앱에서 새로운 버전을 확인하고 설치할 수 있도록 만들어 보겠습니다.

---

✔️ 1. 현재 프로젝트의 업데이트 환경 확인하기

먼저 현재 프로젝트의 설정을 확인해 보겠습니다.

Huni Roulette는 다음과 같은 환경으로 구성되어 있습니다.

항목	현재 설정
개발 환경	Electron
빌드 도구	Electron Forge
Windows 설치 방식	Squirrel.Windows
소스 코드 저장소	GitHub Private Repository
배포 방식	GitHub Release

이전 글에서는 `npm run make` 명령어로 설치 파일을 생성하고, `GitHub Release` 에 업로드해 다른 사람도 앱을 설치할 수 있도록 했습니다.

 

이번에는 여기서 한 단계 더 나아가, 새로운 버전이 출시됐을 때 사용자가 설치 파일을 직접 내려받아 실행하지 않아도 업데이트할 수 있도록 구현할 예정입니다.

🔹 자동 업데이트를 구현하는 방법

자동 업데이트는 업데이트 파일을 어디에 보관하고, 프로그램이 어떤 경로를 통해 새로운 버전을 확인할지에 따라 구현 방법이 달라집니다.

대표적으로 다음과 같은 방법을 사용할 수 있습니다.

• 공개 GitHub Release 활용 : GitHub 저장소의 Release에 업데이트 파일을 등록하고, 프로그램이 새로운 버전을 확인하도록 구성합니다. 공개 저장소를 이용하면 별도의 업데이트 서버를 직접 운영하지 않아도 됩니다.
• 별도의 파일 저장소 활용: Amazon S3와 같은 클라우드 스토리지에 업데이트 파일을 올리고, 해당 경로를 통해 업데이트를 제공합니다.
• 업데이트 서버 직접 운영: 별도의 서버를 구성해 업데이트 확인과 파일 배포 방식을 직접 관리합니다. 필요한 경우 인증과 접근 권한도 함께 설정할 수 있습니다.

이번에는 별도의 서버를 직접 구축하는 대신, 공개 GitHub 저장소를 이용하는 방식을 선택하겠습니다.

현재 사용 중인 소스 코드 저장소는 비공개로 유지하고, 자동 업데이트에 필요한 파일만 별도의 공개 저장소에서 제공하도록 구성할 예정입니다.

 

이렇게 하면 소스 코드 전체를 공개하지 않고도 공개 GitHub Release를 이용한 업데이트 방식을 적용할 수 있습니다.

다만 공개 저장소에 올린 설치 파일과 Release 정보는 누구나 볼 수 있으므로, 공개해도 되는 파일만 업로드해야 합니다.

🔹 공개용 Repository를 별도로 만드는 이유

현재 개발에 사용하는 Repository는 소스코드가 공개되지 않도록 Private으로 유지하고 있습니다.

하지만 이번에 사용할 `update.electronjs.org` 서비스를 이용하려면 대상 앱의 GitHub Repository가 공개되어 있어야 합니다.

 

따라서 기존 개발 Repository를 공개로 변경하는 대신, 배포 파일을 관리하는 Public Repository를 별도로 만들겠습니다.

이렇게 구성하면 다음과 같은 장점이 있습니다.

• 소스코드 보호: 개발용 Repository는 Private으로 유지할 수 있습니다.
• 간편한 배포: 공개용 Repository의 GitHub Release를 통해 업데이트 파일을 제공할 수 있습니다.
• 별도 서버 불필요: 업데이트 서버를 직접 구축하거나 운영할 필요가 없습니다.

 

다만 공개용 Repository에 등록한 설치 파일과 Release 정보는 누구나 확인하고 내려받을 수 있습니다. 소스코드를 비공개로 유지하는 것과 설치 파일을 공개하는 것은 별개이므로, 공개해도 괜찮은 파일만 등록해야 합니다.

이번에는 다음과 같이 구성하겠습니다.

• 개발용 Repository: 기존 Huni Roulette 소스코드 관리
• 배포용 Repository: 설치 파일과 자동 업데이트에 필요한 파일 관리

---

✔️ 2. 자동 업데이트용 GitHub Repository 준비하기

먼저 GitHub에서 자동 업데이트 파일을 제공할 공개 저장소를 만들어 보겠습니다.

🔹 새로운 Repository 생성하기

GitHub에 접속한 뒤 새로운 Repository를 생성합니다.

Repository 이름은 예를 들어 `huni-roulette-releases` 처럼 배포용이라는 점을 알아보기 쉽게 지정하면 됩니다.

이때 Public을 선택하고 Repository를 생성합니다.

이렇게 하면 저장소의 소스 코드 개발 과정과 업데이트 파일 배포 과정을 분리할 수 있습니다.

🔹 배포용 Repository 주소 확인하기

Repository를 생성했다면 주소를 확인합니다.

예를 들어 GitHub 계정이 `my-Id`이고 Repository 이름이 `huni-roulette-releases` 라면 주소는 다음과 같은 형태입니다.

https://github.com/my-Id/huni-roulette-releases

이 주소는 뒤에서 자동 업데이트 기능을 설정할 때 사용합니다.

위 주소는 형식 예시이므로, 실제 구현할 때는 본인이 생성한 Repository 주소로 변경해야 합니다.

🔹 업데이트용 저장소에 올릴 Release 파일 확인하기

이 저장소에는 프로그램의 자동 업데이트에 필요한 Release 파일을 올릴 예정입니다.

`npm run make` 명령어로 빌드하면, `out/make/quirrel.windows/` 경로에 다음과 같은 파일이 생성됩니다.

• Huni Roulette Setup.exe: 앱 설치 파일
• Huni Roulette-full.nupkg: 업데이트에 필요한 패키지
• RELEASES: 업데이트 파일을 확인하기 위한 정보

실제 파일명은 프로젝트 설정과 앱 이름에 따라 달라질 수 있습니다.

 

이전 글에서는 설치 파일인 `Setup.exe` 를 중심으로 배포 과정을 진행했습니다. 하지만 자동 업데이트를 사용하려면 `Setup.exe`  뿐 아니라 `RELEASES` 와 `*-full.nupkg` 파일도 필요합니다.

 

이 파일들은 이후 공개용 Repository의 GitHub Release에 등록할 예정입니다. 지금은 Release를 생성하지 않고 파일의 종류와 역할만 확인한 뒤, 자동 업데이트 설정을 마치고 실제 배포를 진행하겠습니다.

---

✔️ 3. 업데이트에 필요한 파일과 설정 확인하기

이제 프로젝트에서 자동 업데이트를 처리할 방법을 준비하겠습니다.

Electron에는 앱이 업데이트를 확인하고 적용할 수 있도록 `autoUpdater` API가 제공됩니다.

이번에는 업데이트 확인과 다운로드, 사용자 알림 등의 처리를 간단하게 구성할 수 있는 `update-electron-app` 패키지를 사용하겠습니다.

🔹 ① 버전 번호 확인하기

자동 업데이트에서는 현재 설치된 앱의 버전과 새로 배포된 버전을 비교하게 됩니다.

따라서 `package.json`의 버전 번호를 확인합니다.

{
  "name": "huni-roulette",
  "version": "1.0.1"
}

현재 진행하면서 만든 Roulette은 1.0.1 버전까지 변경된 상태입니다.

이후 등록할 GitHub Release의 태그도 앱 버전에 맞춰 `v1.0.1`, `v1.0.2`와 같이 관리할 예정입니다.

버전 번호가 제대로 관리되지 않거나 Release 태그가 올바르지 않으면 업데이트 대상 버전을 찾지 못할 수 있으므로 주의해야 합니다.

🔹 ② 자동 업데이트 모듈 설치하기

이번에는 Electron 앱에서 업데이트 확인과 다운로드를 처리할 수 있도록 `update-electron-app` 모듈을 설치하겠습니다.

프로젝트 폴더에서 다음 명령어를 실행합니다.

npm install update-electron-app

설치가 완료되면 `package.json`에 해당 모듈이 추가되었는지 확인합니다.

이 모듈을 사용하면 업데이트 확인, 다운로드, 업데이트 적용을 위한 기본적인 과정을 직접 모두 구현하지 않아도 됩니다.

---

✔️ 4. main.js에 자동 업데이트 코드 추가하기

이제 `update-electron-app` 패키지를 사용해 자동 업데이트 기능을 추가하겠습니다.

🔹 ① 패키지 불러오기

먼저 `main.js` 상단에 다음 코드를 추가합니다.

const {
  updateElectronApp,
  UpdateSourceType
} = require('update-electron-app');

`updateElectronApp`은 업데이트 확인과 다운로드를 처리하고,

`UpdateSourceType`은 업데이트를 제공할 위치를 지정할 때 사용합니다.

🔹 ② 업데이트할 Repository 설정하기

다음으로 자동 업데이트에 사용할 공개용 Repository를 지정합니다.

updateElectronApp({
  updateSource: {
    type: UpdateSourceType.ElectronPublicUpdateService,
    repo: 'GitHub계정명/huni-roulette-releases'
  }
});

여기서 `repo`에는 GitHub 계정명 또는 조직 이름과 Repository 이름을 입력합니다.

예를 들어 공개용 Repository 주소가 다음과 같다면,

https://github.com/my-Id/huni-roulette-releases

다음과 같이 설정하면 됩니다.

 

repo: 'my-Id/huni-roulette-releases'

`my-Id`와 `huni-roulette-releases`는 예시이므로, 실제로 생성한 Repository 정보에 맞게 변경해야 합니다.

🔹 ③ 실제 설치된 앱에서만 실행하기

자동 업데이트 기능은 개발 중인 앱이 아니라 실제로 패키징한 앱에서 사용하도록 구분하는 것이 좋습니다.

이를 위해 Electron의 `app.isPackaged` 속성을 활용할 수 있습니다.

 

기존 `main.js`에서 `app` 객체를 이미 불러오고 있으므로, 별도로 다시 선언할 필요는 없습니다.

if (app.isPackaged) {
  updateElectronApp({
    updateSource: {
      type: UpdateSourceType.ElectronPublicUpdateService,
      repo: 'GitHub계정명/huni-roulette-releases'
    }
  });
}

`app.isPackaged`는 현재 앱이 패키징된 상태인지 확인하는 속성입니다.

• true: 패키징된 앱
• false: 개발 환경에서 실행 중인 앱

이렇게 설정하면 개발 중에는 업데이트 확인을 생략하고, 패키징된 앱에서만 자동 업데이트 기능을 실행할 수 있습니다.

 

const { app, BrowserWindow, Menu, Notification, ipcMain } = require('electron');
const path = require('path');

const {
  updateElectronApp,
  UpdateSourceType
} = require('update-electron-app');

if (require('electron-squirrel-startup')) {
  return;
}

const createWindow = () => {
  const win = new BrowserWindow({
    width: 420,
    height: 720,
    resizable: true,
    backgroundColor: '#1B1B2F',
    webPreferences: {
      // 화면(index.html)에서 앱 버전을 안전하게 가져오기 위한 preload 스크립트
      preload: path.join(__dirname, 'preload.js')
    }
  });

  win.loadFile('index.html');

  // 설치가 끝나고 Squirrel이 앱을 처음 실행시켜줄 때는
  // --squirrel-firstrun 인자가 함께 붙습니다. 이때만 안내 알림을 띄웁니다.
  if (process.argv.includes('--squirrel-firstrun')) {
    showFirstRunNotification();
  }
};

function showFirstRunNotification() {
  if (!Notification.isSupported()) return;

  new Notification({
    title: '설치가 완료되었습니다!',
    body: '바탕화면에 바로가기가 생성되었습니다.'
  }).show();
}

app.whenReady().then(() => {
  Menu.setApplicationMenu(null); // 기본 메뉴바 제거 (File, Edit 등)

  // package.json의 version 값을 화면에 전달해주는 통로
  ipcMain.handle('get-app-version', () => app.getVersion());

  if (app.isPackaged) {
    updateElectronApp({
      updateSource: {
        type: UpdateSourceType.ElectronPublicUpdateService,
        repo: 'GitHub계정명/huni-roulette-releases'
      }
    });
  }  
  
  createWindow();

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow();
    }
  });
});

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

 

🔹 ④ 업데이트 설정 확인하기

코드를 추가했다면 다음 항목을 확인합니다.

• 공개용 Repository의 계정명과 이름이 정확한가?
• 공개용 Repository가 Public으로 설정되어 있는가?
• GitHub Release에 올바른 버전 태그가 등록되어 있는가?
• Release에 `RELEASES`, `*-full.nupkg`, `Setup.exe`가 등록되어 있는가?

`*-delta.nupkg` 파일은 선택 사항이며, 생성되었다면 함께 등록할 수 있습니다.

 

설정이 잘못되어 있거나 필요한 파일이 누락되면 새로운 버전을 찾지 못하거나 업데이트에 실패할 수 있습니다.

🔹 ⑤ 자동 업데이트는 언제 실행될까?

`update-electron-app`은 기본적으로 앱 실행 시 업데이트를 확인하고, 이후 10분 간격으로 다시 확인합니다.

 

새로운 버전이 발견되면 다음과 같은 순서로 진행됩니다.

1. 앱에서 새로운 버전이 있는지 확인합니다.
2. 업데이트 파일을 백그라운드에서 다운로드합니다.
3. 다운로드가 완료되면 업데이트 적용 여부를 묻는 안내창이 표시됩니다.
4. 사용자가 재시작을 선택하면 업데이트가 적용됩니다.

---

✔️ 5. 새로운 버전 배포 및 자동 업데이트 테스트하기

이제 자동업데이트 설정을 마쳤다면, 실제로 업데이트가 동작하는지 확인해 보겠습니다.

개발 환경에서 앱을 실행하는 것만으로는 설치된 프로그램의 업데이트 과정을 제대로 확인하기 어렵습니다.

따라서 자동 업데이트 코드가 포함된 `v1.0.1`을 먼저 배포하고 설치한 뒤, 새로운 버전인 `v1.0.2`를 배포해 업데이트가 정상적으로 진행되는지 확인하겠습니다.

🔹 ① v1.0.1 빌드 및 GitHub Release 등록하기

먼저 자동 업데이트 코드를 추가한 현재 프로젝트의 버전이 1.0.1인지 확인합니다.

`package.json`에서 다음과 같이 버전이 설정되어 있어야 합니다.

"version": "1.0.1"

이제 설치 프로그램을 생성합니다.

npm run make

빌드가 완료되면 다음 경로에서 생성된 파일을 확인합니다.

out/make/squirrel.windows/

자동 업데이트에 필요한 주요 파일은 다음과 같습니다.

• RELEASES
• *-full.nupkg
• Setup.exe

실제 파일명은 프로젝트 이름과 버전에 따라 달라질 수 있으므로, 생성된 파일명을 그대로 사용합니다.

파일을 확인했다면 업데이트용 공개 Repository에서 `v1.0.1` 태그로 GitHub Release를 생성하고, 필요한 빌드 결과물을 등록합니다.

이때 Release는 Draft나 Pre-release가 아닌 일반 공개 Release로 생성해야 합니다.

 

1. Tag

v1.0.1

 

2. Release title

Huni Roulette v1.0.1

 

3. Release notes

## 변경 사항
- 자동 업데이트 기능 추가
- 앱 버전 표시 기능 유지

## 안내
- Huni Roulette v1.0.1 설치 파일입니다.

 

🔹 ② v1.0.1 설치 및 버전 확인하기

방금 생성한 `v1.0.1` 설치 파일을 실행해 Huni Roulette를 설치합니다.

설치가 완료되면 프로그램을 실행하고 화면 하단에 다음과 같이 표시되는지 확인합니다.

Version 1.0.1

이제 자동 업데이트 기능이 포함된 프로그램이 설치되었습니다.

이 프로그램을 그대로 유지한 상태에서 다음 버전으로 업데이트되는지 테스트하겠습니다.

🔹 ③ 프로그램 버전을 1.0.2로 변경하기

이제 소스 코드 저장소에서 간단한 수정사항을 추가합니다.

예를 들어 화면에 표시되는 문구를 변경하거나 작은 UI 수정을 적용할 수 있습니다.

변경사항을 적용한 뒤 터미널에서 다음 명령어를 실행합니다.

npm version patch

이 명령어를 실행하면 버전이 1.0.1에서 1.0.2로 변경됩니다.

package.json에서 버전이 변경되었는지 확인한 다음 새로운 설치 파일을 생성합니다.

npm run make

빌드가 완료되면 다음 경로에서 v1.0.2 빌드 결과물을 확인합니다.

out/make/squirrel.windows/

🔹 ④ 공개용 Repository에 v1.0.2 Release 등록하기

이제 업데이트용 공개 Repository에서 v1.0.2 태그로 새로운 GitHub Release를 생성합니다.

v1.0.1을 배포할 때와 마찬가지로 다음 파일들을 등록합니다.

• RELEASES
• *-full.nupkg
• Setup.exe

파일명이 실제 빌드 결과와 일치하는지 확인하고, 이번에는 v1.0.2 빌드 결과물을 등록합니다.

이렇게 하면 공개 Repository에 기존 버전인 v1.0.1과 새로운 버전인 v1.0.2가 함께 존재하게 됩니다.

🔹 ⑤ 기존 설치 프로그램에서 자동 업데이트 확인하기

이제 앞서 설치한 v1.0.1 프로그램을 실행한 상태에서 자동 업데이트가 동작하는지 확인합니다.

새로운 버전이 정상적으로 감지되면 업데이트 파일이 다운로드되고, 패키지의 동작 방식에 따라 업데이트 적용을 위한 재시작 과정이 진행됩니다.

업데이트가 완료되면 프로그램을 다시 실행하고 화면 하단에 다음과 같이 표시되는지 확인합니다.

버전이 1.0.2로 변경되었다면 기존에 설치한 프로그램에서 새로운 버전으로 업데이트되는 과정을 확인한 것입니다.

---

✔️ 6. 업데이트가 정상적으로 되지 않을 때 확인할 부분

자동 업데이트가 동작하지 않는다면 다음 항목을 확인합니다.

① Repository 주소 확인하기

main.js에 설정한 GitHub 계정명과 저장소 이름이 정확한지 확인합니다. 업데이트용 저장소는 Public으로 설정되어 있어야 합니다.

 

② Release 파일 확인하기

각 버전의 Release에 RELEASES, *-full.nupkg 파일이 등록되어 있는지 확인합니다. Setup.exe만으로는 자동 업데이트에 필요한 파일이 부족할 수 있습니다.

 

③ 버전 태그와 Release 상태 확인하기

v1.0.1처럼 올바른 버전 태그를 사용하고, Release가 Draft나 Pre-release가 아닌 일반 공개 상태인지 확인합니다.

 

④ 설치된 프로그램에서 테스트하기

개발 환경이 아닌 실제 설치된 프로그램을 실행해 업데이트를 확인합니다. 업데이트 확인과 다운로드에는 시간이 걸릴 수 있으므로 잠시 기다려 봅니다.

---

이번 글에서는 update-electron-app과 GitHub Release를 이용해 Huni Roulette의 자동 업데이트 기능을 구현하고, 기존 버전에서 새로운 버전으로 업데이트되는 과정까지 확인했습니다.

이제 새로운 버전을 배포하면 사용자가 직접 설치 파일을 다시 다운로드하지 않아도 업데이트할 수 있습니다.