# 업데이트

> 새 이미지를 받아 셀프 호스팅 Nodaro를 업데이트하고, 릴리스 태그를 고정하고, 메이저 버전 전에 백업하고, 그 백업을 복원해 롤백하는 방법을 알아보세요.

Source: https://nodaro.ai/ko/docs/self-hosting/updating

셀프 호스팅 Nodaro를 **업데이트**한다는 것은 새 앱 이미지를 받아 앱을 재시작한다는 뜻입니다. 번들된 스택에서는 새 데이터베이스 마이그레이션이 부팅할 때 자동으로 적용되므로, 따로 실행할 것이 없습니다. **메이저** 버전으로 올리기 전에는 릴리스 노트를 읽고 백업하세요. 다운그레이드 방법이 없기 때문입니다.

## 이미지 태그
`main` 브랜치를 빌드할 때마다 앱 이미지 `ghcr.io/nodaroai/nodaro-community`가 `latest`와 해당 커밋 태그로 공개됩니다. 릴리스는 버전 태그 세 개를 추가합니다.

| 태그 | 의미 |
| --- | --- |
| `vX.Y.Z`(예: `v2.0.0`) | 정확히 하나의 빌드이며, 절대 옮겨지지 않습니다. 바이트 단위까지 안정적인 설치를 원하면 이 태그를 고정하세요. |
| `vX.Y` | 한 마이너 버전의 패치를 따라 옮겨집니다. |
| `vX` | 메이저 버전 전체를 따라 옮겨집니다. 기능과 수정은 들어오지만, 호환성을 깨는 변경은 절대 들어오지 않습니다. |
| `latest` | `main`을 따라갑니다. 릴리스 여부와 관계없이 병합된 모든 변경을 받으며, 메이저 버전도 포함됩니다. |
| `<sha>` | 커밋 하나이며, 절대 옮겨지지 않습니다. 정확히 하나의 빌드를 재현하는 또 다른 방법입니다. |

태그는 `.env`의 `NODARO_IMAGE`로 고르세요. 예: `NODARO_IMAGE=ghcr.io/nodaroai/nodaro-community:v1.23.0`.

## 설치 업데이트
앱만 업데이트하려면:

```bash
docker compose -f docker-compose.community.yml pull nodaro
docker compose -f docker-compose.community.yml up -d nodaro
```

Compose 파일, `tools/`의 스크립트, 번들된 서비스까지 업데이트하려면:

```bash
git pull
docker compose -f docker-compose.community.yml pull
docker compose -f docker-compose.community.yml up -d
```

Business 에디션처럼 소스에서 이미지를 빌드한다면 `pull`을 `build`로 바꾸세요. `pull`은 공개된 Community 이미지를 내려받습니다.

마이그레이션은 새 테이블과 추가 열로 앞으로 호환되도록 유지됩니다. 파괴적인 변경은 릴리스 노트에 명시됩니다. 신중해야 한다면 태그나 커밋을 고정하세요.

## 메이저 버전 전에
메이저 버전은 첫 번째 숫자가 바뀌는 버전입니다. 예를 들어 `v1`에서 `v2`로 바뀝니다. 환경 변수, Compose 구성, 내가 의존할 수 있는 동작을 바꿀 수 있는 릴리스는 메이저 버전뿐입니다.

1. [GitHub](https://github.com/nodaroai/app.nodaro.ai/releases)에서 릴리스 노트를 읽으세요.
2. `tools/community-backup.sh`로 백업하세요. [백업과 복원](https://nodaro.ai/docs/self-hosting/backups)을 참조하세요.
3. 업데이트한 다음 `/setup`을 확인하세요. 모든 카드가 초록색이어야 합니다.

## 롤백
마이그레이션 롤백은 없습니다. 데이터베이스는 앞으로만 진행됩니다. 이전 버전으로 돌아가려면:

1. 업데이트 **전에** 만든 백업을 복원하세요: `tools/community-restore.sh <archive>`.
2. 이전 이미지를 고정하세요. 예: `NODARO_IMAGE=ghcr.io/nodaroai/nodaro-community:v1.25.1`. 정확한 `vX.Y.Z` 태그는 절대 옮겨지지 않습니다.
3. `docker compose -f docker-compose.community.yml up -d nodaro`로 시작하세요.

## 관리형 Supabase 프로젝트를 쓸 때
마이그레이션 실행기가 꺼져 있으면, 새 이미지로 재시작하기 **전에** `supabase/migrations/`의 새 파일을 파일 이름 순서대로 적용하세요. 마이그레이션이 빠져도 보통 API는 멈추지 않지만, 그 마이그레이션이 필요한 기능은 해당 테이블이 생길 때까지 `500`으로 응답합니다. [데이터베이스](https://nodaro.ai/docs/self-hosting/database#apply-the-migrations-to-a-managed-project)를 참조하세요.

## 실행 중인 버전
실행 중인 버전은 앱 사이드바와 `/health`에 표시됩니다. 버전을 클릭하면 실행 중인 버전의 릴리스 노트를 볼 수 있습니다. 새 릴리스가 있으면 버전 옆에 빨간 점이 나타납니다. 이때 같은 대화 상자에 최신 릴리스 노트와 정확한 업그레이드 명령이 백업 단계부터 표시됩니다.

업데이트 확인은 하루에 한 번 GitHub API로 익명 요청을 보냅니다. 확인에 실패하면 5분 뒤에 다시 시도하고, 그 뒤로는 성공할 때까지 점점 간격을 늘립니다.

| 변수 | 기본값 | 역할 |
| --- | --- | --- |
| `NODARO_UPDATE_CHECK` | 켜짐 | `off`는 확인을 완전히 끕니다. 설치에서 어떤 요청도 나가지 않고, `GET /v1/version`은 실행 중인 버전만 응답하며, 사이드바는 버전을 일반 텍스트로 표시합니다. 인터넷이 차단된 설치용입니다. |
| `NODARO_UPDATE_CHECK_TOKEN` | 비어 있음(익명) | 업데이트 확인이 공개 릴리스 목록을 읽을 때 쓰는 GitHub 토큰입니다. **스코프가 필요 없습니다**. |

GitHub는 외부 주소 하나당 한 시간에 익명 요청 60회를 허용합니다. 자체 주소가 있는 설치에는 토큰이 필요 없습니다. 다른 사람과 주소를 공유하는 설치에서는 모르는 사람이 이 할당량을 다 써 버릴 수 있습니다. 그러면 버전 레이블이 내장 버전으로 돌아가고, 재시도가 성공할 때까지 릴리스 노트가 비어 있습니다. 로그 줄 `[update-check] … read failed: HTTP 403 (rate limit: 0 of 60 left…)`이 그 신호입니다. 토큰은 `api.github.com`으로만 전송되며 로그에 남지 않습니다.

Compose 파일은 `.env`에서 이 두 변수를 전달하지 않습니다. `nodaro` 서비스의 `environment:` 아래에 추가하세요.

```yaml
nodaro:
environment:
# ...the variables already listed...
NODARO_UPDATE_CHECK: "off"
```

적용하려면 재시작하세요.

## GitHub Actions로 서버 업데이트
저장소에는 SSH로 Nodaro 서버를 업데이트하는 예시 워크플로 `examples/deploy-host.yml`이 들어 있습니다.

1. 내 저장소의 `.github/workflows/` 아래에 복사하세요.
2. 저장소 시크릿 `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_KEY`를 설정하세요.
3. 스크립트의 설치 디렉터리와 Compose 명령을 내 서버에 맞게 조정하세요.
4. **Actions** 탭에서 직접 실행하고, 배포할 이미지 태그를 고르세요.

이 워크플로는 서버에 연결해 `docker compose pull`과 `docker compose up -d`를 실행하고, `/health`가 응답할 때까지 최대 90초 기다린 다음 오래된 이미지 레이어를 제거합니다. 브랜치 푸시로 프로덕션 배포를 시작하지 말고, 환경마다 다른 시크릿 이름을 쓰세요.

## 자주 묻는 질문

### 셀프 호스팅 Nodaro는 어떻게 업데이트하나요?

docker compose -f docker-compose.community.yml pull nodaro를 실행한 다음 docker compose -f docker-compose.community.yml up -d nodaro를 실행하세요. 번들된 스택에서는 부팅할 때 데이터베이스 마이그레이션이 자동으로 적용됩니다.

### 어떤 이미지 태그를 고정해야 하나요?

바이트 단위까지 안정적인 설치를 원하면 정확한 vX.Y.Z 태그를 고정하세요. vX.Y는 한 마이너 버전의 패치를 받고, vX는 호환성을 깨는 변경 없이 기능과 수정을 받으며, latest는 메이저 버전을 포함해 병합된 모든 변경을 따라갑니다.

### 이전 버전으로 다운그레이드할 수 있나요?

직접은 할 수 없습니다. 데이터베이스 마이그레이션은 앞으로만 진행되기 때문입니다. 업데이트 전에 만든 백업을 복원한 다음 이전 이미지 태그를 고정하세요. 메이저 버전마다 그 전에 백업하세요.

### 업데이트가 있는지 어떻게 알 수 있나요?

새 릴리스가 있으면 앱 사이드바의 버전에 빨간 점이 표시됩니다. 클릭하면 릴리스 노트와 정확한 업그레이드 명령을 볼 수 있습니다. 확인은 하루에 한 번 GitHub로 보내는 익명 요청입니다.

### 인터넷이 차단된 설치에서 업데이트 확인을 끌 수 있나요?

네. docker-compose.community.yml에서 nodaro 서비스의 environment 블록 아래에 NODARO_UPDATE_CHECK를 off로 추가하세요. 그러면 설치에서 어떤 요청도 나가지 않고, 버전은 일반 텍스트로 표시됩니다.