업데이트

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

이미지 태그

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

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

설치 업데이트

앱만 업데이트하려면:

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

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

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에서 릴리스 노트를 읽으세요.
2. tools/community-backup.sh로 백업하세요. 백업과 복원을 참조하세요.
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으로 응답합니다. 데이터베이스를 참조하세요.

실행 중인 버전

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

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

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

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

  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초 기다린 다음 오래된 이미지 레이어를 제거합니다. 브랜치 푸시로 프로덕션 배포를 시작하지 말고, 환경마다 다른 시크릿 이름을 쓰세요.