> For the complete documentation index, see [llms.txt](https://orbitron.gitbook.io/orbitron-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://orbitron.gitbook.io/orbitron-docs/documentation/ko/user-guide/installation/migration-guide.md).

# 마이그레이션 가이드

이 가이드는 이전 버전의 Orbitron에서 자동 업데이트 시스템으로 마이그레이션하는 방법을 설명합니다.

## 🔍 마이그레이션이 필요한 경우

다음 위치에 Orbitron이 설치되어 있다면 마이그레이션이 권장됩니다:

* `~/.orbitron/bin/`
* `/usr/local/bin/` (수동 설치)
* 기타 사용자 정의 위치

새로운 설치 위치는 `~/.local/bin/orbitron`이며, 버전 관리 시스템(`~/.local/share/orbitron/versions/`)을 사용합니다.

## 🚀 자동 마이그레이션 (권장)

자동 설치 스크립트는 기존 설치를 감지하고 대화형 마이그레이션을 제공합니다.

### 1단계: 설치 스크립트 실행

```bash
# macOS / Linux
curl -fsSL https://orbitron.megaone.com/api/install.sh | bash

# Windows (PowerShell)
irm https://orbitron.megaone.com/api/install.ps1 | iex
```

### 2단계: 마이그레이션 프롬프트

기존 설치가 감지되면 다음과 같은 메시지가 표시됩니다:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Old Installation Detected
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Old version: v0.1.11 (in ~/.orbitron/bin/)
New version: v0.1.12 (will be installed to ~/.local/bin/)

Would you like to migrate the old installation?
  YES: Backup old version, install new version, update PATH
  NO:  Keep both versions (you can remove old version later)

Migrate old installation? (Y/n):
```

### 3단계: 선택

#### 옵션 A: 마이그레이션 (Y 또는 Enter - 권장)

`Y`, `yes` 또는 `Enter`를 누르면:

```
Migrating old installation...

✅ Backed up v0.1.11 to ~/.local/share/orbitron/versions/0.1.11
✅ Removed old binary from ~/.orbitron/bin/
✅ Removed old PATH from ~/.zshrc
```

그 후 새 버전 설치가 진행됩니다:

```
✅ Installed to ~/.local/share/orbitron/versions/0.1.12
✅ Updated symlink at ~/.local/bin/orbitron
✅ Added PATH to ~/.zshrc
```

#### 옵션 B: 두 버전 유지 (N 또는 n)

`N` 또는 `n`을 누르면:

```
Keeping both versions...

⚠️  Old version will remain at: ~/.orbitron/bin/
    New version will be installed to: ~/.local/bin/
```

설치 완료 후:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ✅ Installation Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️  Both old and new versions are installed

To use the new version:
  1. Make sure ~/.local/bin is in your PATH
  2. Remove or rename the old binary:
     rm ~/.orbitron/bin/orbitron

To verify which version is running:
  orbitron --version
  which orbitron
```

### 4단계: 자동 업데이트 설정

마이그레이션 선택 후 자동 업데이트 설정을 선택합니다:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Auto-Update Configuration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Would you like to enable automatic updates?
You can change this setting later with: orbitron config set autoUpdate <true|false>

Enable auto-update? (Y/n):
```

* `Y`, `yes` 또는 `Enter`: 자동 업데이트 활성화
* `N` 또는 `n`: 자동 업데이트 비활성화

### 5단계: 설치 완료 및 확인

PATH 설정이 성공하면:

```bash
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  ⚡ Next Steps
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

To start using orbitron, reload your shell:

  source ~/.zshrc

Then verify the installation:

  orbitron --version
```

Windows의 경우:

```
To start using orbitron, reload your PowerShell profile:

  . C:\Users\username\Documents\PowerShell\Microsoft.PowerShell_profile.ps1

Or simply open a new PowerShell window.

Then verify the installation:

  orbitron --version
```

## 🎯 마이그레이션 후 확인

터미널을 재시작하거나 설정 파일을 다시 로드한 후:

```
# 버전 확인
orbitron --version

# 설치 위치 확인
which orbitron
# 출력: /Users/username/.local/bin/orbitron

# 자동 업데이트 설정 확인
orbitron config get autoUpdate
```

## ⚠️ 주의 사항

### 마이그레이션 시 YES 선택한 경우

* 이전 바이너리는 자동으로 백업됩니다: `~/.local/share/orbitron/versions/{old_version}/`
* 이전 설치 위치(`~/.orbitron/bin/` 또는 `/usr/local/bin/`)에서 바이너리가 제거됩니다
* 쉘 설정 파일에서 이전 PATH가 자동으로 제거됩니다 (Unix/Linux/macOS만)
* `~/.orbitron/bin/` 디렉토리가 비어있으면 자동으로 제거됩니다

### 마이그레이션 시 NO 선택한 경우

나중에 수동으로 이전 버전을 제거할 수 있습니다:

```
# 이전 바이너리 제거
rm ~/.orbitron/bin/orbitron

# 디렉토리가 비어있으면 제거
rmdir ~/.orbitron/bin
rmdir ~/.orbitron  # 다른 파일이 없으면
```

### 설정 파일

기존 설정 파일(`~/.orbitron.json`)은 자동으로 호환되므로 별도의 변경이 필요하지 않습니다.

더 자세한 문제 해결은 [문제 해결 가이드](/orbitron-docs/documentation/ko/user-guide/installation/troubleshooting.md)를 참조하세요.

## 🔗 관련 문서

* [설치 가이드](https://github.com/AlphaCode-AI/orbitron-docs/tree/main/docs/ko/user-guide/installation/README.md) - Orbitron 설치 방법
* [자동 업데이트 가이드](/orbitron-docs/documentation/ko/user-guide/installation/auto-update.md) - 자동 업데이트 설정 및 사용
* [문제 해결](/orbitron-docs/documentation/ko/user-guide/installation/troubleshooting.md) - 일반적인 문제 및 해결 방법